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Using This Book 

Purpose 

SAS/C Development System User’s Guide, Volume 2: Debugger, Utilities, 
Assembler describes how to use some of the major tools available to 
the SAS/C programmer under AmigaDOS: the debugger, the macro 
assembler, the optimizer, and the various utilities that are part of the 
SAS/C Development System. 

“Using This Book” describes how you can best use this book. It 
describes the book’s intended audience, the audience’s prerequisite 
knowledge, the book’s organization and its conventions, and additional 
documentation that is available to you. 


Audience 

This book assumes you have a working knowledge of the the C or 
C+ + language and the AmigaDOS operating system. To use the 
SAS/C Macro Assembler, you also need a working knowledge of 
assembly language. For a list of publications you can use to learn the C 
language or the AmigaDOS operating system, refer to the “Additional 
Documentation” section at the end of “Using This Book.” 


How to Use This Book 

This section gives an overview of the book’s organization and content. 
The book’s chapters are described, followed by a section on how to use 
each chapter. 

Organization SAS/C Development System User’s Guide, Volume 2: Debugger, Utilities, 
Assembler is divided into five parts; the chapters and appendixes 
contained in each part are described here: 

Part 1: Using the SAS/C Debugger 

Part 1 contains nine chapters that discuss CodeProbe and how to use it 
to debug your program. 

Chapter 1, “Getting Started” 

explains what CodeProbe does, how it works, and what tasks are 
involved in debugging a program. This chapter also describes how 
to compile and link your program under CodeProbe control. 
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Chapter 2, “Customizing the Debugging Environment” 

describes the commands and options you can use to customize the 
environment in which you debug your program. 

Chapter 3, “Debugging C Programs” 

contains an example of debugging a simple C program. It describes 
the CodeProbe commands most frequently used for stepping 
through your program, displaying code and data, and modifying 
code or data. 

Chapter 4, “Debugging C++ Programs” 

contains an example of debugging a simple C+ + program. This 
chapter illustrates how to specify various CodeProbe commands and 
parameters when you are debugging C+ + programs. 

Chapter 5, “Debugging Shared Libraries” 

describes how to use CodeProbe to debug resident libraries. 

Chapter 6, “Debugging Multitasking Programs” 

describes how to use CodeProbe with applications that spawn 
additional tasks. 

Chapter 7, “Using AREXX Macros with CodeProbe” 

describes how to use AREXX macros from inside CodeProbe. This 
chapter contains a list of valid AREXX commands. 

Chapter 8, “Using the Cross Debugger” 

describes how to run your executable code from a serially- 
connected Amiga system. 

Chapter 9, “Command and Built-In Function Reference” 

describes each CodeProbe command and built-in function in detail. 

Part 2: Using the SAS/C Utilities 

Part 2 contains only one chapter. This chapter discusses the SAS/C 

utilities. 

Chapter 10, “Utility Reference” 

describes each of the utilities (such as smake, scopts, and tb) 
provided by the SAS/C Development System. 

Part 3: Using the SAS/C Macro Assembler 

Part 3 contains only one chapter. This chapter discusses how to use 

assembly language with the C and C+ + languages. 

Chapter 11, “Using Assembly Language with the C and C+ + 

Languages” 

describes how to communicate between the C and C+ + languages 
and the assembler. You can incorporate assembler routines as part 
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of your C/C+ + program or call C/C+ + functions from assembly 
language. 

Part 4: Using the SAS/C Optimizers 

Part 4 contains only one chapter. This chapter discusses how to use 

the SAS/C Optimizers. 

Chapter 12, “Optimizing Your Code” 

describes what the global optimizer, peephole optimizer, and 
instruction scheduler do and how to run the optimizers during 
compilation. 

Part 5: Appendixes 

Part 5 contains two appendixes. 

Appendix 1, “diff File-Matching Algorithm” 

describes the algorithm used by the diff utility to compare files. 

Appendix 2, “Source Code for Debugger Examples” 

contains the source code for the examples used in Chapters 3, 4, 5, 
and 6. 

What You The following table points you to specific chapters in this book for 
Should Read information on particular topics. For other references, refer to 

“Additional Documentation” later in this section. 


For information on 

You should read 

compiling, linking, and running your program 
under the debugger 

Chapter 1 

customizing your debugging environment 

Chapter 2 

using the most common debugger commands 

Chapters 3 and 4 

debugging resident libraries 

Chapter 5 

debugging multitasking programs 

Chapter 6 

using ARE XX macros 

Chapter 7 

running your program on one machine and 
debugging it on another machine 

Chapter 8 
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Typographical 

Conventions 


Syntax 

Conventions 


Conventions 

This section covers the typographical and syntax conventions used in 
this book. 


The SAS/C books for AmigaDOS use special fonts to depict specific 
types of information. These typographical conventions are as follows: 


roman 

monospace 


oblique 


italic 


is the basic type style used for most text, 
is used to show example statements or programs. 
Monospace is used also for items specific to the 
C and C+ + languages, such as the names of functions, 
header files, and keywords. To distinguish between C 
and C+ + function names, the names of C+ + 
functions are followed by parentheses, as in setf ( ) . 
is used for argument, variable, or parameter values 
when they are shown as displayed by the SAS/C 
Development System. For example, a compiler message 
may contain a character string from your program, 
is used for terms that are defined and for arguments or 
variables whose values are supplied by the user. For 
example, you should enter an appropriate filename 
when you see filename. 


This book uses the following conventions for syntax: 


monospace 


italic 

U 

(square brackets) 
. . . (ellipsis) 


indicates commands, keywords, and switches that 
should be spelled exactly as shown. These 
arguments may or may not be optional, depending 
on whether they are enclosed in square brackets, 
indicates arguments for which you supply a value, 
indicate an optional argument when they surround 
the argument. 

indicates that you can repeat the argument or 
group of arguments preceding the ellipsis any 
number of times. 


(vertical bar) 


means to choose one item from a group of items 
separated by the bars. 
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The following example illustrates these syntax conventions: 
env [function \ integer] 

env 

is a command name, so it appears in monospace type. 
function 

is a function for which you supply the name, so it appears in italic 
type. 

[function | integer ] 

are both optional, so they are enclosed in square brackets. 
function | integer 

indicates that you can specify only one of the items separated by the 
vertical bar. 


Additional Documentation 

The following sections list documentation you may find helpful in using 
the SAS/C Development System. 

SAS If you are interested in SAS documentation, you need to contact the 
Documentation Book Sales department by writing, calling, or faxing the Institute: 

SAS Institute Inc 
Book Sales Department 
SAS Campus Drive 
Cary, NC 27513 
919-677-8000 

SAS/C Development System 

This book is part of a set of publications for the SAS/C Development 
System. There are three other publications in the set: 

□ SAS/C Development System User’s Guide, Volume 1: Introduction, 
Compiler, Editor describes how to 

□ install the SAS/C Development System on your Amiga system 

□ use your development environment 

□ create files in the editor 

□ compile and link C files. 
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□ SAS/C Development System Library Reference describes how to 

□ access libraries 

□ create your own libraries 

□ use header files to reduce the amount of time and space required 
by your program. 

□ SAS/C Development System Quick Reference, contains reference 
tables for the library functions, compiler and linker options, and 
debugger commands. 

These volumes are sold together as a set. 

Other The following sections list additional reference material specific to the 
Documentation C and C+ + languages, Amiga and AmigaDOS programming, and the 

Motorola 68xxx microprocessor. 

C Language 

The following books describe the C programming language: 

American National Standards Committee (1990), American National 
Standard for Information Systems — Programming Language C, 
Document Number X3J1 1/90-013, Washington, D.C.: X3 
Secretariat: Computer and Business Equipment Manufacturers 
Association. 

Harbison, Samuel P. and Steele, Guy L., Jr. (1990), C: A Reference 
Manual, Third Edition, Englewood Cliffs, NJ: Prentice-Hall, Inc. 

Kernighan, Brian W. and Ritchie, Dennis M. (1988), The C 
Programming Language, Second Edition, Englewood Cliffs, NJ: 
Prentice-Hall, Inc. 

C+ + Language 

The following books describe the C+ + programming language: 

Ellis, Margaret A. and Stroustrup, Bjarne. (1990), The Annotated 
C+ + Reference Manual, Reading, MA: Addison-Wesley Publishing 
Company. 

Ranade, Jay and Saba, Zamir. (1992), C+ + Primer For C 
Programmers, New York, NY: McGraw-Hill, Inc. 

Sessions, Roger. (1992), Class Construction in C and C++: object- 
oriented programming fundamentals, Englewood Cliffs, NJ: Prentice- 
Hall, Inc. 

Stroustrup, Bjarne. (1991), The C+ + Programming Language, Second 
Edition, Reading, MA: Addison-Wesley Publishing Company. 
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Amiga and AmigaDOS 

The following books provide information specifically about 

programming on the Amiga system. Most of the examples in these 

books are written in the C or assembler languages. 

Commodore-Amiga, Inc. (1991), Amiga Hardware Reference Manual, 
3rd Edition, Reading, MA: Addison-Wesley Publishing Company. 

Commodore-Amiga, Inc. (1991), Amiga ROM Kernel Reference Manual: 
Devices, 3rd Edition, Reading, MA: Addison-Wesley Publishing 
Company. 

Commodore-Amiga, Inc. (1991), Amiga ROM Kernel Reference Manual: 
Includes and Autodocs, 3rd Edition, Reading, MA: Addison-Wesley 
Publishing Company. 

Commodore-Amiga, Inc. (1991), Amiga User Interface Style Guide, 
Reading, MA: Addison-Wesley Publishing Company. 

Commodore-Amiga, Inc. (1991), The AmigaDOS Manual, 3rd Edition, 
New York, NY: Bantam Books. 

Commodore-Amiga, Inc. (1992), Amiga ROM Kernel Reference Manual: 
Libraries, 3rd Edition, Reading, MA: Addison-Wesley Publishing 
Company. 

Motorola 68xxx The following books contain information specifically about 

programming the Motorola 68xxx microprocessor. 

Motorola, Inc. (1987), MC68881/MC68882 Floating-Point Coprocessor 
User’s Manual, First Edition, Englewood Cliffs, NJ: Prentice-Hall, 

Inc. 

Motorola, Inc. (1989), MC68030 Enhanced 32-Bit Microprocessor 
User’s Manual, Second Edition, Englewood Cliffs, NJ: Prentice-Hall, 
Inc. 

Motorola, Inc. (1989), Programmer’s Reference Manual, Phoenix, AZ: 
Motorola Literature Distribution. 

Contacting You can contact Commodore Application and Technical Support at the 
CATS following address: 


Commodore Business Machines, Inc. 
Department C 
1200 Wilson Drive 
West Chester, PA 19380 


215-431-9180 
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Changes and Enhancements 

Changes and Enhancements for Version 6.0 
of the CodeProbe Debugger 

The following sections describe some of the changes and enhancements 
for Version 6.0 of the CodeProbe debugger: 

□ Cross debugger support is provided via the serial port or a 
communications network. 

□ Debugging of shared libraries and devices has been simplified. 

□ C expression parsing is allowed with most debugger commands. 

□ The ability to display ranges within arrays is provided. 

□ The alias and define commands provide greater flexibility. 

□ 68881 floating-point registers are supported. 

□ Motorola fast floating-point format (ffp) display is provided. 

n The env and where commands enable you to look back up the 
function call chain. 

□ The args command displays arguments to the current function. 

□ More compact debugging format saves space on disk. 

□ The AmigaDos Version 2.0 look and feel is provided, including public 
screens and three-dimensional look. 

□ The call command enables you to call application functions directly 
from the debugger. 

□ The source command enables you to specify the new name of a 
source file. 

□ The symbol, shell, and window commands have been added. 

□ Calls, Modules, and Memory windows have been added. 

□ Enhanced AREXX support is provided. 

□ Cross-referenced online help is provided in a separate window. 

□ The log command provides a Dialog window command logging 
capability. 

□ The j ump command provides the ability to change the current location. 



xxii Changes and Enhancements 


Changes and Enhancements for Version 
6.50 of the CodeProbe Debugger 

The following sections describe some of the changes and enhancements 

for Version 6.50 of the CodeProbe debugger: 

□ The debugger now recognizes C++ member functions, constructors, 
destructors, and operator functions in the break and display 
commands. 

□ CodeProbe allows you to choose between overloaded function names 
when setting breakpoints or displaying variables in C + + code. 

□ The debugger now knows about class member variables in C+ + 
member functions. 

□ The debugger allows you to debug functions defined in header files. 

□ CodeProbe now has full support for #line statements. Previous 
versions of the debugger only supported #line statements if the line 
numbers were monotonically increasing. Now #line numbers can 
jump back and forth at will. 

□ The quit command supports a new option, -abort. This option quits 
CodeProbe without calling your program’s exit function. You can use 
this if you think your program will crash if exit is called. 

□ Under AmigaDOS 2.0 and later, CodeProbe now supports the System 
Default font that you select with the Preferences Font Editor. 

□ Use of the debugger’s AREXX port is now supported in line mode. 

□ CodeProbe can now catch devices as well as libraries and tasks, which 
allows you to easily debug devices. 

□ CodeProbe now supports SegTracker. SegTracker is provided with the 
SAS/C Development System, and it allows CodeProbe to to find 
SegLists for new tasks caught by the debugger. Since CodeProbe can 
now find the SegList, you d.o not need to find it. You can catch a 
process and debug it seamlessly with a simple symload command 
with no arguments. 
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Introduction 

CodeProbe* is a powerful source-level debugger that enables you to 
monitor, line by line, the behavior of programs written in C, C++, 
assembler, or a combination of these. 

This chapter explains what CodeProbe does, how to start the 
debugger, and how to enter commands. This chapter also briefly 
explains how CodeProbe works. 


* Throughout this manual, the terms CodeProbe and the debugger are used 
interchangeably to refer to this debugger program. 



Overview of CodeProbe 

CodeProbe allows you to examine and modify variables, address and 
data registers, and user-specified memory locations. It allows you to 
stop the execution of your program at any point, and it enables you to 
examine both the source code and the assembler instructions generated 
for your program at the same time so you can see what is happening 
at the assembly language level. 

CodeProbe allows you to: 

□ single-step through programs either in the source code or the 
generated assembler code. 

□ set breakpoints on source lines or on individual assembly language 
statements. 

□ continue program execution until a specified function or line number 
is reached, or until a variable contains a specified value or its value 
changes. 

□ examine variables and code at the source language level. 

□ display data types — including structures, unions, arrays, enums, 
typedefs, and bit fields — in their C or C+ + formats. 

□ display memory dumps in a variety of formats. 

□ continuously watch any variable, array element, or structure 
member. 

□ assign a value to a variable. 

□ fill an area of memory. 

□ copy one array or structure to another. 

□ copy a string from one place to another. 

□ view and manipulate register data. 

□ access storage classes of data, including automatic, static, and 
register as well as external. 

CodeProbe also helps you debug multitasking programs. Any new 
tasks or processes created by a program that is being debugged are 
automatically under debugger control. For multitasking programs, 
CodeProbe allows you to: 

□ set breakpoints for any task under debugger control. 

□ display the state of any task, including the stack and registers. 

□ start and stop tasks selectively. 

□ intercept tasks that are executing independently and attach them to 
the debugger. For example, you may want to intercept a task if it 
enters an infinite loop or waits indefinitely on a message port. 
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Debugging a Program 

Debugging a program using CodeProbe involves three basic steps: 

1. Compile and link your program using one of the debug options 
with the sc command. 

2. Start the debugger. 

3. Run your program to completion under debugger control. 

4. Quit the debugger. 

The remaining sections of this chapter contain the information you 
need to perform these steps. 


Compiling and Linking Your Program 

Before invoking CodeProbe you must compile and link your program 
with debugging information. To compile and link your program from 
the Shell, specify one of the debug options and the link option in 
the sc command, as in the following example: 

sc debug=symbolf lush link filename 

From the Workbench, you can use the s copts utility to specify 
options and then compile and link by double-clicking on the Build 
icon. (For more information, refer to Chapter 8, “Compiling and 
Linking Your Program,” of the SAS/C Development System User’s 
Guide, Volume 1.) 

If you plan to rename or move your source files before using the 
debugger, you may want to use the sourceis compiler option to set 
the name of the source file in the object file and in the debugging 
information. For a complete description of sourceis, refer to SAS/C 
Development System User’s Guide, Volume 1. 

The amount of debugging information available to CodeProbe is 
determined by the debug option that you specify. 

Deciding Which 
debug Option To 

Use 


The following list describes each of the debug options. 
debug=line or debug=l 

generates the line number/offset table only, which allows the 
debugger to match the lines in a source file with the executable 
code. You can set breakpoints at source lines and step through the 
source code. However, for external variables and functions, only 
the address of a symbol is available. There is no information about 
the symbol’s attributes. For this reason, the debugger displays any 



variable as a long and issues the following warning message: 

> display fahr 

accessing extern with unknown attributes - assuming long 

1101004800 ( 0x4 1A00000 ) 

If you compile with debug=line and you want to display a 
variable in its proper form, either use one of the dump commands 
or use a type cast with the display command: 

> display (float) fahr 

20 

(See Chapter 9, “Command and Built-in Function Reference,” for 
more information about the display and dump commands.) 

The line option is useful with large programs or when disk 
space is limited because it produces much smaller object files. The 
line option also provides all the information needed by the 
disassembler, omd. 
debug=symbol or debug=s 

generates full debugging information for all global and local 
variables, all functions, and all types that are referenced in the 
module, including structure, union, enum, and typedef 
types. You can set breakpoints at source lines, display or alter data 
symbolically, set watches on variables or areas of memory, and list 
source code. If you compile with debug=symbol (or higher), the 
display command correctly formats all data declared in the 
module. 

Debug information for a structure or union definition is 
generated only if it is used in a typedef declaration or as either a 
global or local variable. That is, if the structure or union is defined 
in a header file that is included by your program, but the tag 
associated with that structure or union is not used by your 
program, then the compiler does not generate debug information 
for that tag. Most source modules use numerous include files that 
contain definitions that are never actually used. By limiting debug 
information to include only referenced definitions, the output 
module size is greatly reduced. 
debug=symbolf lush or debug=sf 

generates full debugging information for all global and local 
variables, all functions, and all types that are referenced in the 
module, including structure, union, enum, and typedef 
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types. This option does not generate debugging information for 
types that are defined but not referenced in the module. The 
symbol flush option also causes the code generator to flush all 
registers to variable locations at source line boundaries. 

debug= symbol flush is the recommended option for debugging 
user programs. 

Note: Any module compiled with this option should be 
recompiled without this option before it is placed into production 
because this option generates a larger, slower executable module. 
debug=full or debug=f 

generates full debugging information for all symbols that are 
declared or defined in the module even if there is no reference to 
the symbols in the generated code. 
debug=fullf lush or debug=f f 

generates full debugging information for all symbols that are 
declared or defined in the module even if there is no reference to 
the symbols in the generated code. The fullflush option also 
causes the code generator to flush all registers to variable locations 
at source line boundaries. 

Note: Any module compiled with this option should be 
recompiled without this option before it is placed into production 
because this option generates a larger, slower executable module. 

To make full use of the debugger’s features, you should always use 
either the symbol, symbolflush, full, or fullflush option. 

You can mix modules compiled with different levels of debugging in 
the same program. 

To eliminate unnecessary loading and storing of values, the compiler 
often manipulates a variable’s contents in registers over several lines 
of code without replacing the results in the variable. Therefore, the 
correct value of a variable at any given time may be in a register 
rather than in the variable’s memory location. If you display the value 
of the variable with the display command, the debugger displays 
the value in memory, not the value in the register, which may not be 
the correct value. If you think that the debugger is not displaying the 
correct values, you can do either of the following: 

□ examine the code in mixed mode. To specify mixed mode, enter the 
opt source mixed command. In mixed mode, you can tell if the 
value of a variable is being kept in a register rather than being 
flushed to memory, and you can then use the register command 
rather than the display or dump commands to determine the 
variable’s value. 
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Compiling and 
Linking as 
Separate Steps 


□ recompile the file with the symbol flush or fullflush option. 
The symbol flush and fullflush options force the compiler to 
place the correct values of variables into the memory whenever the 
compiler reaches the end of a line of source code. However, the 
symbol flush and fullflush options generate extra code that is 
required to store, and perhaps reload, the values. 

Only the symbol flush and fullflush options affect the quality of 
code generated by the compiler. The other options do not affect code 
generation and differ only in the amount of symbolic information they 
pass to the linker. 

If you are not concerned with debugging production quality code, 
you should use the symbol flush option, since the difference in 
generated code will have little effect. Even if you are attempting to 
create production software, you should begin your debugging by using 
the symbol flush option and then recompile with the symbol option 
when most of your bugs have been detected and fixed. 

If you want to debug exactly the program you intend to use, you 
should use symbol or full, and you should debug in mixed mode so 
that you can see the machine instructions corresponding to your 
source lines. 

As described earlier, you can compile and link your program by 
specifying the link option in the sc command. 

You can also compile and link your program in separate steps. If you 
do not specify the link option on the sc command line, you need to 
call the linker, slink, to link your program. Use the slink 
command only if you are limited by the sc command. For the majority 
of programs, linking with the s c command is much simpler and easier 
than linking with the slink command. 

To compile and link your program in separate steps, you must 
compile with one of the debug options and link with the addsym 
option, as in the following example: 

sc debug=symbolf lush filename.c 
slink addsym from LIB:c .o+filename.oto filename 
lib LIB:sc.lib+LIB:amiga.lib 

The addsym option forces slink to generate symbolic information 
for global symbols in libraries and for any file that does not have 
debug information. If you compile and link by specifying the link 
option in the sc command, the compiler passes the addsym option to 
the linker. 
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After you have debugged and recompiled your program, you can use 
the stripdebug option in slink to remove debugging information 
from the final executable module: 

slink from executable-file to destination-file stripdebug 

For more information on the slink command, refer to Chapter 8, 
“Compiling and Linking Your Program,” of the SAS/C Development 
System User’s Guide , Volume 1. 


Running CodeProbe 

You can run CodeProbe from the Workbench or from the Shell. 
CodeProbe makes the following assumptions: 

□ The program that you specify on the command line exists in the 
current directory or somewhere on the command search path, as 
specified by the AmigaDOS path command. 

□ The modules that comprise your program have been compiled with 
one or more of the debugging options and have been linked using 
the addsym option of the linker (as described in “Compiling and 
Linking Your Program,” earlier in this chapter). 

□ Source files for modules that you will be accessing exist in either the 
current directory, your special source path list (as specified by the 
opt search command), or the directory in which the module was 
compiled. 

Running To start CodeProbe from the Shell command line, enter the cpr 
CodeProbe command as follows: 

From the Shell 

cpr [cpr-options] program-name [program-arguments] 

The program-name and program-arguments are the name of your 
program and any arguments it expects. “Specifying CodeProbe 
Options,” later in this chapter, describes each of the cpr-options that 
you can specify. 

If a program-argument is a string that contains spaces, you must 
enclose the string in double quotes (" "), as in the following example: 

cpr myprog "first string" "second string" 

Any data that your program writes to stdout is written to the 
Shell in which you invoked CodeProbe. 
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Running 
CodeProbe 
From the 
Workbench 


The sc : starter_pro ject drawer contains a tool called Debug 
and a corresponding Debug, info icon. If you ran the scsetup 
utility on your development directory, then the tool and its icon were 
copied into your directory. If you have not run the scsetup utility, 
you can either run scsetup on your directory or copy the tool and 
its icon into your development directory. 

To run CodeProbe from the Workbench, click once on the Debug 
icon, then hold down the Shift key and double-click on the icon for 
your executable module. CodeProbe opens a Debug window into which 
it can write messages and data that are sent to stdout, then 
CodeProbe immediately displays the Source and Dialog windows. 

If you do not specify the -cli option, any data that your program 
writes to stdout is written to the standard I/O window opened by 
the startup code. If you specify -cli, any data your program writes to 
stdout is written to the Debug window. You can use the F9 (Swap) 
function key to change between the debugger windows and the Debug 
or standard I/O window. 

If you want to specify an option, you can add it to the Debug icon 
as a tool type. You can also add a program name as a tool type; 
however, Debug would always debug that program. Remember, 
CodeProbe assumes that any options specified after the program name 
are options to your program, not to CodeProbe. To add program- 
arguments to the icon, add the -cli option as the last cpr option, 
then add the name of your executable module followed by its 
command-line options. For a description of how to add tool types to an 
icon by using the Information window, refer to the descriptions of the 
Information option or Information window in Using the System 
Software (Commodore-Amiga, Inc. 1990). 

If a program-argument is a string that contains spaces, you must 
enclose the string in double quotes (" ") as described previously 
under “Running CodeProbe From the Shell.” 

By default, Debug invokes sc:c/cpr. If you rename or move cpr, 
Debug can find it if you assign the full pathname of the debugger to 
the environment variable sc/cprpath with the AmigaDOS setenv 
command as follows: 


setenv sc/cprpath pathname 
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Running 
CodeProbe in 
Line Mode 


Specifying 

CodeProbe 

Options 


You also can run CodeProbe as a line-mode debugger by starting it 
with the -line option. In line mode, the debugger displays its output 
in the current Shell window. 

You may want to use CodeProbe in line mode if you want to run the 
debugger from: 

□ an AREXX script. 

□ a Shell that has been started from a remote login from another 
machine. 

□ a Shell that has been started across a serial line. For information 
about starting a Shell over a serial line, see the description of the 
AUX: device in The AmigaDOS Manual, 3rd Edition. 

You may also want to run CodeProbe in line mode if you are 
redirecting output using the Shell redirection commands. 

CodeProbe supports the following options: 

-b[uffer] size 

specifies the size in bytes of the Dialog window buffer. By default, 
the Dialog window saves the last 4096 bytes displayed so that you 
can scroll backwards and review output. 

-cli 

instructs CodeProbe to invoke your application as a Shell (CLI) 
process. CodeProbe passes arguments to the application through the 
normal command line interface. This option is the default if 
CodeProbe is invoked from a Shell. The option is necessary if 
CodeProbe is invoked from the Workbench screen, and you want 
your program to run as if invoked from a Shell. 

-command commands 

executes the specified debugger commands at startup. The 
commands are executed after go main if the -startup option is 
not specified or after the profile script if -startup is specified. 

For example, the command 

cpr -command "proceed; display fahr" program-name 

executes to main, steps over 1 line of code, and displays the 
variable fahr before giving control to you. 

-i 

sets up a screen in interlace mode. By default, CodeProbe opens a 
new screen using the specifications set up by Preferences for 
Workbench screens. To force a screen to be opened in interlace 



mode, include the - i option before typing the application command 
name. 

-line 

starts CodeProbe in line mode. See “Running CodeProbe in Line 
Mode,” earlier in this chapter, for more information. 

-nommu 

tells CodeProbe not to use the MMU. This option is useful only if 
you have a 68020 or higher CPU. 

If your machine is running Enforcer and has a 68020 or higher 
CPU, CodeProbe tries to use the MMU to stop references to illegal 
memory. For these machines, specifying -nommu tells the debugger 
not to verify memory in the MMU tables before trying to access the 
memory. However, if Enforcer is running, you will still not be able 
to display illegal memory. 

-noprofile 

suppresses execution of the CodeProbe startup file. When 
CodeProbe is invoked, it automatically executes a script file named 
cprinit, which must be located in either the current directory or 
ENV: sc. If the startup file is in the current directory, CodeProbe 
does not search ENV : sc. 

-scfreen] screen-name 

tells CodeProbe to open its windows on the named public screen. 

By default, CodeProbe creates a new public screen named 
SC—CPR. 1 when it is invoked. If you specify -screen, CodeProbe 
looks for an existing public screen with the specified name, and if it 
finds one, CodeProbe uses that screen to display its windows. If a 
screen with the given name does not exist, CodeProbe creates a new 
one with that name. To use the Workbench screen, specify 
-screen workbench. 

Public screens are a feature of Intuition 2.0. For users of earlier 
versions of Intuition, this option is not generally useful. However, 
specifying -screen workbench causes CodeProbe to use the 
Workbench screen on older releases. 

-startup 

suppresses the automatic go main that is normally executed by the 
debugger on startup. This option is useful you want to step through 
the startup code or debug constructors or autoinitialization 
functions that run before main. If you specify -startup, the 
application process does not perform any type of initialization 
before control is given to you. 

If the quit, start, or restart commands are invoked and an 
application process has not exited, the debugger normally calls 
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exit to clean up any process resources that may not have been 
freed. However, if you invoked CodeProbe with the -startup 
option, exit is not called. 

-w 

runs CodeProbe on the Workbench screen. Specifying -w is 
equivalent to specifying -screen workbench. 

-wb 

tells CodeProbe to invoke the application as a Workbench process. 

It passes arguments to the application through a Workbench startup 
message. This option is the default if CodeProbe is invoked from the 
Debug icon. The option is necessary if CodeProbe is invoked from 
a Shell, but you want the application to run as if invoked from the 
Workbench screen. 

-wd[ialog] left top width height 
-wr [eg is ter] left top width height 
-ws[ource] left top width height 
-ww[atch] left top width height 

specifies startup window coordinates for the Dialog, Register, 

Source, and Watch windows, respectively. Window coordinates are 
measured in character positions. A width or height of 0 causes the 
window to extend to the screen border on the right or bottom, 
respectively. For example, to open the Source window in position 
(0,1) and make the Source window 50 characters (columns) wide 
and 12 lines long, you would specify: 

cpr -ws 0 1 50 12 program-name 

Note: The Register and Watch windows are not displayed on 
startup. However, when they are opened by pressing the 
appropriate function key (either FI or F4), they will open to the 
coordinates specified on the command line. 

suppresses the copyright banner that is displayed at startup. 


Using the Windowing Interface 

If you do not invoke CodeProbe with the -line option, then the 
debugger runs in windowing mode. Initially, CodeProbe opens the 
Source and Dialog windows, as shown in Display 1.1. 
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Display 1.1 

Initial CodeProbe 
Window 



CodeProbe has many additional windows. For example, you can open 
the Memory, Register, and Watch windows, as shown in Display 1.2. 


Display 1.2 

Five Different 
CodeProbe Windows 



BBS9D 
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CodeProbe displays your source code in the Source window, and you 
can enter debugger commands and view the results in the Dialog 
window. 

CodeProbe has 11 different windows, as described in the following 
list: 

Calls window 

displays a stack traceback showing the calling sequence for the 
program being debugged. Each level of the traceback represents the 
state of the machine when a function was called. The state of the 
machine is also known as its environment. By double-clicking on a 
desired traceback entry in the Calls window, you can return 
CodeProbe to a previous environment. You will then see the code 
that was being executed at that time in the Source window, and you 
can see the contents of the registers as they were before the call in 
the Register window. CodeProbe displays your current location in 
the Dialog window. 

For example, suppose you have a main function that calls a 
function named sort, which in turn calls a function named swap. 
When the execution of your program reaches the swap function, 
the calling sequence main, sort, swap is displayed in the Calls 
window. By double-clicking on the entry for the main function, you 
can return the machine to the state it was in when main called 
sort. You will see the source code that was executed and be able 
to view what was in the registers at the point at which main called 
sort. However, your program will still be executing at the same 
point in the swap function. Therefore, you can examine local 
variables, and they will have the values they had when main called 
sort, but global variables may have changed. If you single-step 
through the program, the code displayed in the Source window 
returns back to the last line executed in swap, and execution 
continues. 

Dialog window 

allows you to enter commands and view the results of those 
commands. Many of the same commands available through the pull- 
down menus can be invoked directly at the command line in the 
Dialog window. 

Help window 

displays help information for each of the CodeProbe commands as 
well as other selected topics. You can open the Help window by 
entering the help command, by selecting the Help window from 
the View pull-down menu (as described later in this chapter), or by 
pressing the Help key. 



Input window 

opens automatically if the menu option you select requires input. 

For example, if you select the List Default option from the Options 
pull-down menu, CodeProbe opens an Input window into which you 
should enter the number of default lines that you want to be 
displayed by the list command. You can exit out of an Input 
window without entering input by pressing the escape (Esc) key. 
Memory window 

displays a dump of memory in both character and hexadecimal 
format or disassembles code. 

Message window 

displays text passed to it by the wmsg command. This window 
opens automatically if you enter the wmsg command. 

Modules window 

displays a list of all the modules within your program. 

Output window 

displays output that is sent to stdout by your program or by the 
debugger: 

□ If you invoke CodeProbe from a Shell command line, the Output 
window is that Shell. 

□ If you invoke CodeProbe from the Workbench, the Output 
window is the window opened by your program’s startup code. 

□ If you invoke CodeProbe from the Workbench with the -cli 
option, the Output window is the Debug window opened by 
CodeProbe before it opens the Source and Dialog windows. 

Register window 

displays the contents of all registers and the current values of the 
processor flags. Any registers that have been modified since the last 
breakpoint are highlighted. You can open the Register window by 
pressing the F4 key. 

Source window 

displays the source code for the module currently being executed. 

As execution proceeds, the Source window is continually updated to 
show the current position. The current position (the line about to 
be executed) and any breakpoints that have been set are 
highlighted. 

Watch window 

displays the values of the expressions or ranges for which you have 
set a watch or watch break. For example, if you set a watch or 
watch break on a variable, the Watch window is automatically 
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updated each time the value of that variable changes. You can open 
the Watch window by pressing the FI key. 

With the exceptions of the Input and Message windows, you can use 
the View menu to open any window, as described in “Using Pull-Down 
Menus,” later in this chapter. With the exception of the Input window, 
you can use the window command to open any of the windows, as 
follows: 

window window-name 

You can close CodeProbe windows by specifying the off option in the 
window command: 

window window-name off 

When more than one window is open, the frame of the active 
window is highlighted. The active window is the window that can 
receive input. AmigaDOS Version 2.0 and above changes the color of 
the frame to indicate whether it is active, and Version 1.3 ghosts the 
title bar when a window is not activated. 

Most CodeProbe windows are displayed with the standard 
AmigaDOS gadgets: depth, zoom, sizing, close, scroll bars. You can 
move CodeProbe windows in the same way that you move AmigaDOS 
windows: point at the title bar and hold down the left mouse button. 


Getting Help 

The online help system provides help information for CodeProbe 
commands and built-in functions and their parameters. As described 
earlier, you can open the Help window by entering the help 
command, by selecting the Help window from the View pull-down 
menu, or by pressing the Help key. Display 1.3 shows the CodeProbe 
Help window. 
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Display 1.3 

CodeProbe Help 
Window 


Entering 
Commands on 
the Command 
Line 



Entering Commands 

You can enter debugger commands in four different ways: 

□ entering commands on the command line 

□ using pull-down menus 

□ using function keys 

□ using menu accelerator keys. 

Whether you run CodeProbe in line mode or in windowing mode, the 
most flexible method of entering debugger commands is typing them in 
the command line. The command line is marked by the > prompt. You 
can enter any of the debugger commands described in Chapter 9 in the 
command line. 

You can enter commands and options in either uppercase or 
lowercase, and you can abbreviate command and option names. 
Frequently, you need to enter only 1, 2, or 3 letters of a command. In 
Chapter 9, the optional letters of a command or option name are 
enclosed in brackets ([]). In the Help window, required letters are 
captialized, and optional letters are in lowercase. For example, you can 
enter the return command as return, retur, or ret. 
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Extending Commands across Lines 

You can extend a command line across several input lines by ending 
all lines except the last line with a backslash (\) followed immediately 
by a carriage return. A command line can contain up to 256 
characters. 

Entering Several Commands in One Line 

To enter more than one debugger command in the same command 
line, separate the commands with a semicolon (;). For example, the 
following command line runs the alias command followed by the 
display command: 


alias tb where;d x 


Using Command-line Editing 

If you are working in windowing mode, you can use command-line 
editing keys to enter commands. 

The way in which command-line editing works, is controlled by 
which combination of editing modes you are using. 


insert mode 
overwrite mode 
function mode 
numeric mode 


Any characters that you type on the command line 
are inserted between existing characters. 

Any characters that you type on the command line 
overwrite any existing characters. 

Pressing a key on the numeric keypad performs 
the action printed on the front of the key. 

Pressing a key in the numeric keypad produces the 
number or sign printed on the top of the key. 


The first character in the title bar of the Dialog window is an I if insert 
mode is active. If overwrite mode is active, the first character is an 0. 

You can use the Insert (ins) key on the numeric keypad to switch 
between insert and overwrite mode. (Use the zero key on the numeric 
keypad to switch between insert and overwrite modes on the A1000.) 

The third character in the title bar is an F if the numeric keypad is 
in function mode or an N if the numeric keypad is in numeric mode. 

To switch between the numeric and function modes, press the F10 key. 

CodeProbe remembers each command that you enter until you quit 
the debugger. Using command-line editing functions, you can scroll 
backward and forward through these commands, edit them, and re- 
enter them without having to retype the entire command. Table 1.1 
describes the command-line editing functions. The keypad must be in 
function mode to use these editing functions. 
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Table 1.1 

Command Line 



Keys 

Description 

Editing Functions 

Control-X 

erases the current line 


Control-A 

toggles insert/overstrike 


Control-Keypad-1 

erases from the cursor to the end of the line 


Keypad-1 

moves the cursor to the end of the line 


Keypad-7 

moves the cursor to the start of the line 


Keypad-0 

starts inserting at the cursor 


Keypad-. (Del) 

deletes the character under the cursor 


Keypad-4 (-«— ) 

moves the cursor left one position 


Keypad-6 (— *■) 

moves the cursor right one position 


Shift-keypad-4 (-*— ) 

moves the cursor left one word 


Shift keypad-6 (— ►) 

moves the cursor right one word 


Keypad-Enter 

sends the line to the program as input 


Keypad-8 (f) 

recalls the previous Dialog window command 


Keypad-2 (|) 

goes to the next Dialog window command 


Keypad-9 (PgUp) 

moves the page up 


Keypad-3 (PgDn) 

moves the page down 

Using Pull-Down 

You can enter the most 

common debugger commands by selecting 

Menus 

options from pull-down menus. As with other Amiga applications, you 


use the right mouse button to control menu functions. Table 1.2 lists 

Table 1.2 

Pull-down Menu 

CodeProbe menu options and their command-line equivalents. 

Menu Item 

Command-line Equivalent 

Items 

File Menu 
Module 

list \module 


Line 

list [ line ] 1 [ address ] 


Find Current Line 

env 


( continued ) 
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Table 1.2 (continued) . . 

Menu Item Command-line Equivalent 


Execute 

execute [ script-name ] 

Refresh 

Ctrl L 

Paste 

no equivalent 

Quit 

Options Menu 

quit 

Source Mode 

opt source 
( c 1 asm Imixed ) 

Radix Default 

opt radix ( hex 1 decimal ) 

Context Lines 

opt context [ integer ] 

List Default 

opt list [integer] 

Unassemble Default 

opt unassemble [integer] 

String Length 

opt strlen [integer] 

Array Length 

opt arrdim [integer] 

Range Length 

opt range len [integer] 

Autoswap Mode 

opt autoswap (onloff) 

Echo Mode 

opt echo (onloff) 

Instruction Bytes 

opt ibytes (onloff) 

Ignore Path 

opt ignorepath (onloff) 

Case Sensitivity 

opt case (onloff) 

Maximum Bad Characters 

opt badchar [integer] 

Step Into ResLib 

opt reslib (onloff) 

Catch New Devices 

opt devices (onloff) 

Catch New Tasks 

opt catch (onloff) 

(continued) 
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Table 1.2 (continued) 


Menu Item 

Command-line Equivalent 

View Menu 


Calls 

window calls 

Modules 

window modules 

Register 

window register 

Watch 

window watch 

Source 

window source 

Dialog 

window dialog 

Output 

window output 

Memory 

window memory 

Help 

window help 

Run Menu 


Trace Into 

trace 

Proceed Over 

proceed 

Go 

go 

Go Until 

go [ location ] 

Return 

return [value] 

Start 

start [command-line] 

Break Menu 


Set 

break [location] 

List 

blist 

Clear 

bclear [arguments] 

Enable 

benable [arguments] 

Disable 

bd is able [arguments] 

All Clear 

bclear * 


( continued ) 
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Table 1.2 ( continued ) 


Menu Item 

Command-line Equivalent 

Watch Menu 

Set 

watch [ location J 

Break 

wbreak [arguments] 

List 

wlist 

Clear 

wclear [ arguments ] 

Enable 

wenable [ arguments ] 

Disable 

wdi sable [ arguments ] 

All Clear 

wclear * 

Memory Menu 

Size 

no equivalent 

Display As 

no equivalent 

Base Address 

no equivalent 


Note: The File menu has two items called Line and Find Current 
Line that automatically list lines of source code in the Dialog window. 
These options are displayed as Address and Find Current Address 
when the debugger is in assembler mode. When prompted for an 
address after choosing the Address item, you should enter a 
hexadecimal value. The 0 x prefix is not required. The Source window 
will disassemble code beginning at the specified address. 

Using Function The debugger title bar displays the functions that are assigned to the 
Keys function keys: 

1=Watch 2=Zoom 3=Recall 4=Reg 5=Again 6=Next 7=Into 8=0ver 9=Swap 
10=KPad 

In addition to the function keys, there are three keys with special 
functions: Help, Control-L, and Control-W. Table 1.3 describes each of 
the function and special keys. 
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Table 1.3 

Function and Special 
Keys 


Using Menu 
Accelerator 
Keys 


Key 

Action 


FI 

opens or closes 

the Watch window 

Shift-Fl 

opens or closes 

the Source window 

F2 

zooms or unzooms the active window 

F3 

recalls the last < 

command * 

Shift-F3 

recalls the previous command * 

F4 

opens or closes 

the Register window 

F5 

re-executes the j 

last command * 

F6 

activates the next window 

F7 

steps into a fine 

i or instruction (trace) 

F8 

steps over a lini 

3 or instruction (proceed) 

F9 

switches between the debugger and application screens 

F10 

switches between numeric and function mode 

Help 

executes the help command 

Control-L 

refreshes the screen 

Control-W 

refreshes the screen 


* The Dialog window must be active to recall or re-execute commands. 


Many menu options are also associated with menu accelerator keys 
(also called keyboard shortcuts). These shortcuts are displayed to the 
right of the option in the pull-down menus. You can execute these 
shortcuts by pressing the Right Amiga key in combination with another 
specified key. For example, to clear all breakpoints, hold down the 
Right Amiga key and press A. 

Table 1.4 fists the actions performed by the debugger menu 
accelerator keys. 
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Table 1.4 

Menu Accelerator 
Keys 


Specifying 
Parameters to 
Commands 


Key 

Menu 

Action 

A 

Break 

clears all breaks 

B 

Break 

sets a breakpoint 

c 

Break 

clears a breakpoint 

D 

Break 

disables a breakpoint 

E 

Break 

enables a breakpoint 

F 

File 

refreshes the screen 

G 

Run 

executes the go command 

H 

File 

finds the current line 

L 

Break 

lists the breakpoints 

M 

File 

changes the current module 

N 

File 

finds the line or address 

P 

Run 

steps over the current line or instruction (proceed) 

Q 

File 

quits the debugger 

R 

Run 

returns from the current function 

s 

Run 

restarts the program with same command line 
(start) 

T 

Run 

steps into the current line or instruction (trace) 

w 

Run 

displays stack frame traceback (where) 

X 

File 

executes a debugger command script from a file 


Many commands require special parameters such as an address or C 
expression. The following sections describe each of the special 
parameters required by the various CodeProbe commands: 

□ address 

□ array-slice 

□ expression 

□ location 

□ number 



□ range 

□ register 

□ subrange 

□ type 

□ variable. 

address 

An address parameter is any expression that denotes an address. The 
expression can be any of the following: 

□ a hexadecimal constant 

□ a C pointer variable 

□ a register 

□ the result of prefixing 6 to a C identifier of the correct type (not a 
bitfield or register identifier) 

□ the result of arithmetic calculations on other addresses 

□ any C expression that evaluates to a pointer type. 

The following list shows expressions that denote addresses. In these 
expressions, p is a pointer, and i and x are integers. 

Si 

(Si + 8) 

6array[ 3 ] 

Smystruct - x 
P 

0x00C85400 

aO 

(aO + 0x22) 

— this 

myclass: rmemberfunc 

In some cases, a register name may be ambiguous. For example, you 
may have defined a variable sp in your program. In the following 
command, CodeProbe cannot tell whether you want to dump data 
beginning at the variable sp or at the address contained in the register 
SP: 


db sp 

In these cases, the debugger assumes that you are referring to the 
variable sp. However, you can prefix the register name with a dollar 
sign ($) or use the register command to examine the value of the 
SP register even if you have declared a variable named sp. 
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In some commands, it is necessary to specify the type of an object to 
be modified or displayed. If the object is referred to using an address 
constant or register, the value is assumed to be a character pointer 
(char *). 

array-slice 

An array-slice parameter is one of the following: 

□ a contiguous section of a unidimensional array of scalar variables 

□ an ordered selection of elements from a multidimensional array 

□ an ordered selection of members from an array of complex types. 

You can use an array-slice anywhere an array is valid. You can specify 
an array-slice in either of the following formats: 

variable [n. ,m] 
variable [*] 

Note: The inner brackets do not denote optional parameters and 
must be entered as shown if you want to specify index numbers or the 
asterisk (*). 

The advantage of using an array-slice parameter over a range 
parameter (described later in this chapter) is that the array-slice can be 
used to select isolated subcomponents, such as a particular structure 
member from an array of structures. The array-slice parameter can 
also be nested for multidimensional arrays or structure members that 
are arrays themselves. 

If you specify a subrange (as described later in this chapter) as the 
index of an array-slice, those elements within the subrange are selected. 
The asterisk (*) index specifies that all elements of the array are to be 
contained in the array-slice. The following are examples of the array- 
slice parameter: 

a 1 3 . . 7 ] 

matrix[i. . j] [ 1 . .3] 
b[*l 

a [ 3 . . 6 1 ->b 



expression 

Any C expression is accepted as an expression parameter, except those 
that use one or more of the following operators: 


1 = 
>> = 


* = 
/ = 
% = 


C+ + expressions are not supported, so you cannot use overloaded 
operators in an expression in a debugger command. 

The following are valid expressions: 

a(i*8 ] 

p->d[5]+f(3) 

location 

A location parameter specifies a place in the code at which a 
breakpoint is to be set, code is to be unassembled, or a similar action 
is to be performed. When debugging in source mode, a location 
parameter is a line number in a source file or a function entry point. 
When debugging in assembly mode, you may want to place breakpoints 
at specific addresses. To do this, use a hexadecimal address as the 
location parameter. 

You can specify a location parameter as follows: 

$ 

specifies the current location in the current executable, module, and 
function. 

hex-address 

can be any valid absolute address specified as a hexadecimal 
integer. 
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[[executable-name : ][\module\]function] [line] 

can identify any location in any executable. The values for 
executable-name, module, and function can be specified explicitly as 
follows: 

executable-name : 

is the name of the executable image (the program, library, or 
device) containing the location. It is usually specified in 
lowercase. In a program with only one executable image, you do 
not need to specify an executable-name : . If you specify an 
executable image, follow the name with a colon ( : ). The default 
executable image is the current executable. 

\module\ 

is the name of the C source file compiled to yield the specified 
function. If you specify a module name, follow the name with a 
backslash (\). 
function 

is the name of a function in the application. For C+ + , the 
function can be a member function, operator, constructor, or 
destructor, but you need to precede the function name with the 
name of the class for which the function is defined, as follows: 

myclass : : function 
myclass : :operatorx 
myclass : : myclass 
myclass: :~myclass 


line 


can be any of the following: 

integer a line number, relative to the start of the C 
source file containing the function. 

$ the current location. 
e[ntryj the entry to the function (prolog). 
r[eturn] the return from the function (epilog). 


You must enter a space before the line parameter. All other spaces and 
tabs are ignored. If you do not specify the name of an executable, 
module, and/or function, the debugger uses the names from the 
current environment. (For more information, see the description of the 
env command in Chapter 9.) If you specify a function name but do not 
specify a line, the debugger uses the first execution line of the specified 
function. 



The following are examples of locations: 


main 

test.c\main 

myprog:test.c\main 

example. de vice : \ serial .c\cmd_handler 70 
myclass: :myfunc 
myclass: :operator+ 
mycxxprog:myclass : rmyfunc 12 

number 

A number parameter is a number in decimal, octal, or hexadecimal 
notation. If you begin the number with a 0 digit, the number is 
interpreted as an octal number. If you begin the number with Ox or 
OX, the number is interpreted as a hexadecimal number, and if you 
begin the number with On or ON, the number is interpreted as a 
decimal number. 

By default, the number is interpreted as a decimal number. You can 
use the opt radix command to change the default. 

The following examples show acceptable values for number 
parameters: 

12345 
0455 
0x380 
0X1849 
On 1 2345 

range 

A range parameter is a contiguous area of memory, and you can 
specify a range in one of two ways: 

start-address . . end-address 
start-address 1 | L length 

In the second form, the length is a number (as described earlier) that 
indicates the number of elements, and the range is from the start 
address through address + number — 1. When the debugger sees a 
solitary 1 or L in a command, it is considered part of a range 
expression. 
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For example, the following pairs of ranges are equivalent: 

0x123456 .. 0x123461 
0x123456 L 11 

Sp[0] .. 6p[ 5 ] 

S p [ 0 ] 1 6 

p[0J .. P [ 5 1 

p[0] 1 6 

The following examples use the names of address registers: 

al . . a2 
a7 1 20 

register 

A register parameter refers to the name of any of the following 680x0 
registers: 

AO - A7 are address registers. Register A7 functions as the stack 
pointer and can be specified as either A7 or SP. 

DO - D7 are general-purpose registers. 

PC is the program counter. 

SP is the stack pointer. 

SR is the status register. It contains the CCR register as well as 
the current processor status. 

CCR is the condition code register. It resides in the lower byte of 
the status register, SR. 

If a math coprocessor is present, the following registers also can be 
specified as the register parameter: 

FPO - FP7 are the floating-point registers. 

FCR is the floating-point control register. 

FSR is the floating-point status register. It contains the current 
floating-point condition codes. 

In some cases, a register name may be ambiguous. See the description 
of the address parameter, earlier in this chapter, for more information. 
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string 

A string parameter can be any standard C or C+ 4- string in double 
quotes ("): 

" string " 

You can continue a string onto the next line by ending the line with a 
backslash (\). The debugger supports ANSI string concatenation: two 
strings adjacent to each other will be combined into one longer string. 

In strings, the debugger supports the C escape sequences shown in 
Table 1.5. 


Table 1.5 

Escape Sequences in 
Character Strings and 
Character Constants 


Escape Sequence 

Meaning 

\n 

newline (0x0 a) 

\t 

horizontal tab (0x0 9) 

\b 

backspace (0x08) 

\r 

carriage return (OxOd) 

\f 

form fee4 (0x0c) 

\ V 

vertical tab (Ox 0b) 

\NNN 

octal constant, where NNN are 3 octal digits 

\xNN 

hex constant, where NN are 2 hexadecimal 
digits 


A backslash followed by any character other than those shown 
previously is interpreted as a plain character. For example, \ \ is a 
string consisting of a single backslash, and a \ " b is three characters 
long: an a, a double quote, and a b. 

The Dialog window does not recognize any of these escape sequences 
when they are displayed. You cannot use the \t escape sequence to 
tab in the Dialog window. The escape sequences are useful in line 
mode and when setting a character string. 
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subrange 

A subrange parameter is a series of contiguous integers, inclusive of its 
bounds. The integers may be either integer constants or variables from 
the program being debugged. You can specify a subrange parameter as 
follows: 

[integer \ variable ] . . [integer \ variable] 

The following are examples of the subrange parameter: 

3. .7 

i. . j 

type 

A type parameter can be any of the data types provided by the C 
language, including: 

char 

unsigned char 
short 

unsigned short 
int 

unsigned int 
long 

unsigned long 
unsigned 
float 
double 
struct name 
union name 
enum name 
class name 

A type also can be any of these C types followed by some number of 
asterisks indicating that the type is a pointer to the base object. 

In addition, the type parameter can take any identifier defined by 
means of a typedef statement if the debugging information for the 
module supplies typedef information. 

CodeProbe considers an int to be four bytes, regardless of whether 
you compiled your program with the shortint option. Use short to 
refer to objects declared int in code compiled with shortint. 



variable 

A variable parameter denotes a data object. The variable can be either 
a simple identifier or an expression referring to an array element, 
structure member, or object pointed to by a pointer. You specify 
variables as follows: 

[[executable-name :][\module\ ] function\]variable 

See the location parameter earlier in this chapter for a description of 
the executable-name, module, and function. 

The following are valid examples of variable parameters: 


max 

array[3] 

array 

ioireadf ile\length 
mystruct->name [ 2 ] 
mystruct 
♦cptr 

main. c\opnf\ count 
opnf \i 

mylib. library :LIBmyfunc\myvar 
myobject .mypublicmember 
myobjectptr->mypublicmember 
mycxxprogrmyclass : :myfunc\mylocalvar 

In C programs, if you have more than one variable with the same 
name, CodeProbe uses the variable that is in scope. 

In C+ 4- programs, a local variable in a member function and a data 
member of the object that invoked the function can have the same 
name. For example, if the variable name is myvar, you can display the 
local variable with: 

display myvar 

To display the data member of the class that invokes the function, use 
the object’s this pointer: 

display this->myvar 

CodeProbe cannot display variables that have the same name as a 
register but begin with a dollar sign such as $d5. 
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Entering Escape You might want to use escape characters in 

Characters 

□ character strings 

□ character constants 

□ other command parameters. 

C character strings consist of text surrounded by double quotes 
("text"). C character constants consist of a single character surrounded 
by single quotes ( ' x ' ). You can use the escape sequences shown in 
Table 1.5 in both character strings and character constants. 

Other command parameters accept different escape characters. Table 
1.6 lists the escape characters that you can use outside of character 
strings and constants. 


Table 1.6 

Escape Sequences in 

Escape Sequence 

Meaning 

Other Command 

\\ 

backslash 

Parameters 

\ ; 

command delimiter 


\ , 

argument delimiter 


\" 

character string/constant delimiter 


\ ' 

constant delimiter/constant delimiter 


\< 

when or macro delimiters 


\) 

when or macro delimiters 


Outside of quotes, a backslash followed by any other character is not 
assigned any special meaning. The backslash and the character are 
interpreted as two distinct characters. Therefore, "b \mod\func" 
sets a breakpoint at function f unc of module mod, and not at a 
function called modfunc. 

Escape sequences are especially useful with the alias command. 
For example, the following command line assigns the two commands 
where and d x to the alias name tb: 


alias tb where\;d x 



Ending Your Program and Quitting the 
Debugger 

Before you quit CodeProbe, you Should allow your program to run to 
completion so that your program can perform its own cleanup. To run 
your program to completion, you can enter the go command until you 
see the following message: 

Program exited with code n. 

To quit the debugger, enter the quit command. CodeProbe calls the 
exit function, which performs some additional cleanup for your 
program. 


How CodeProbe Works 

When you specify one of the debug options to the compiler, the 
compiler generates debugging information in the form of H_DEBUG 
hunks that are placed into the object module for that source. The 
compiler can generate two different types of H—DEBUG hunks: line and 
symbolic. It can also vary the amount of information that goes into the 
symbolic H_DEBUG hunks based on the debug option. 

If you specify debug=line, then the compiler generates an 
H—DEBUG hunk that contains the source filename and a table of source 
line numbers to address offset pairs. CodeProbe uses this table to 
determine which C source lines correspond to which assembler 
instructions. 

If you specify the debug= symbol or debug=full options to the 
compiler, then the compiler generates an h_debug hunk containing 
high-level symbolic debugging information for the source, including 
information for external identifiers, structure and union tags, typedefs, 
local variables, and so on. CodeProbe searches this information when 
trying to display an item in C source mode. 

If you specify the link option in the sc command or the addsym 
option in the slink command, then slink generates an H_ SYMBOL 
hunk in the final executable file. The H_S YMBOL hunk contains a table 
of global symbols and their offsets into the data section. CodeProbe 
uses this global symbol information to locate the start of the symbol, 
but CodeProbe cannot determine its size or type. CodeProbe assumes 
all such symbols are of type lopg. Using addsym may be necessary if 
you are debugging large projects on small machines where there might 
not be enough memory to load symbolic debugging information. 
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Code hunks are described in more detail in Chapter 12, “How the 
Compiler Works,” in the SAS/C Development System User’s Guide , 
Volume 1: Introduction, Compiler, Editor. 
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Introduction 

Your debugging environment is affected by the options with which you 
compile your source file and by the options with which you invoke 
CodeProbe. All of these options are described in Chapter 1, “Getting 
Started.” This chapter describes additional ways in which you can 
customize your debugging environment. You can: 

□ specify a different source file for CodeProbe to use. 

□ create command files that you can execute from inside CodeProbe. 
You can also create an initialization file that is executed each time 
CodeProbe is invoked. 

□ change CodeProbe options using the opt command. 

□ customize existing commands by creating aliases. 

□ define macros for use inside CodeProbe. 


Setting the Source File Location 

When you compile a program with one of the debug compiler options, 
the compiler writes, in the debugging information, the same name that 
you passed to the compiler with the s c command. If you specify a full 
or partial pathname for your source file, the pathname is included. 

By default, when CodeProbe looks for a source file, it looks in: 

1. the name specified in the debugging information 

2. the current directory 

3. each of the directories specified in its search path, in the order in 
which they are specified. 
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If you move or rename your source file before you debug it with 
CodeProbe, you will need to tell CodeProbe where to look for the 
source file. You can tell CodeProbe where to look by using one of three 
methods: 

□ Compile your program with the source is compiler option. The 
sourceis option changes the name that is specified in the 
debugging information. Refer to Chapter 8, “Compiling and Linking 
Your Program,” in SAS/C Development System User’s Guide , Volume 
1 for more information. 

□ Specify the new filename with the source debugger command. The 
source command overrides the filename specified in the debugging 
information. CodeProbe uses the new name throughout the current 
session. 

□ Modify the debugger’s search path with the opt search debugger 
command. You can add and delete directories from the debugger’s 
search path, which is empty by default. To display the current 
search path, enter the opt search command without any 
parameters: 

opt search 

To replace the search path completely, specify the search path: 
opt search dirl dir2 dir3 ... 

To add or delete specific directories to or from the search path, use 
a plus or minus sign in front of the directory list: 

opt search - dirl dir2 dir3 ... 
opt search + dirl dir2 dir3 ... 

For example, the following series of commands 

opt search c: f dfO:, dhO :mysource 
opt search + df1:test 
opt search - df 0 : , c: 

produces the following search path: 


dhO :mysource 
df 1 : test 
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If CodeProbe cannot find the source file for the function it is 
currently executing, it displays the following message: 

Error: error opening source file filename 


Using Command Files 

You can enter any CodeProbe commands into a file, and execute that 
file from inside CodeProbe using the execute command. For 
example, you might want to create a file with the following commands: 

/* cpr command file */ 

opt search dhO:mysource, dfO:mysource, ram: 
opt radix h 
opt ibytes off 

If you named this file cpr opts, you could execute this file from inside 
CodeProbe by entering the following command: 

execute cpropts 

If you want CodeProbe to start the debugger with the same options 
most of the time, you can create a command file that is executed each 
time the debugger is invoked. When CodeProbe is invoked, it looks for 
a file name cprinit in the current directory. If this file does not 
exist in the current directory, CodeProbe looks in the ENV : SC 
directory. If a file named cprinit exists in both directories, the 
debugger uses the file in the current directory. For example, you could 
have a cprinit file that contains the following lines: 

/* This is a debugger profile script for a project */ 

opt source mixed 

proceed 

display argc, argv 

You can enter C-style comments in command files, but you must 
begin and end the comment on the same line. Do not enter comments 
such as the following: 

/* You cannot enter commments like this. 

It doesn't begin and end on the same line. */ 
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CodeProbe executes the cprinit file after the initial go main but 
before any commands specified with the -command option. 


Displaying and Setting Options within 
CodeProbe 

You can use the opt command to display or set options from within 
CodeProbe. To display the default option settings, enter the opt 
command without any parameters: 


Source mode c 

Echo mode Off 

Instruction bytes... Off 

Ignore path Off 

Case sensitivity. .. .Of f 

Context 2 lines 

List default 6 lines 

Unassemble default.. 4 lines 

Radix default Decimal 

String Length 128 

Array Dimension 20 

Range Length 64 

Maximum Bad Chars... 3 
Search path: 

Tab Width 8 

Autoswap mode Off 

Catch New Devices... No 

Step into ResLib Yes 

Current Task sort at 0001DC20 

Catch New Tasks No 


For a complete description of each option, refer to the description of 
the opt command in Chapter 9, “Command and Built-in Function 
Reference.” 
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Displaying 

Aliases 


Creating New 
Aliases 


Using Aliases (alias and unalias) 

You can use the alias command to redefine and customize 
CodeProbe commands. You can use the alias command to 

□ display a list of all currently defined aliases. By default, CodeProbe 
defines several aliases for various dump commands. 

□ create new aliases. 

□ display the definition of an existing alias. 

To display the list of all currently defined aliases and their associated 
commands, enter the alias command without parameters: 


> alias 


da 

dump 

$* 

$ 

asciil 

db 

dump 

$* 

$ 

hexl text 

dc 

dump 

$* 

$ 

decl 

dd 

dump 

$* 

$ 

f loat8 

df 

dump 

$* 

$ 

f loat4 

dffp 

dump 

$* 

$ 

ffp4 

di 

dump 

$* 

$ 

dec4 

dl 

dump 

$* 

$ 

dec4 

dp 

dump 

$* 

$ 

hex4 

ds 

dump 

$* 

$ 

dec2 

dw 

dump 

$* 

$ 

hex2 


To display the definition for an existing alias, enter the alias 
command with only the name argument. For example, to display the 
definition for the d f f p alias, you would enter: 

alias dffp 

To create a new alias, enter the alias command as follows: 
alias alias-name definition 

The definition can be a simple text substitution or it can contain 
positional parameters to be expanded at execution time. Positional 
parameters are specified as $1, $2, $3, and so on. $0 represents the 
alias-name itself. $* represents all command-line parameters. 

If you specify one or more positional parameters, then when you 
enter the alias on the command line, CodeProbe places the parameters 
where you tell it to and throws away any unused parameters. 



If you do not specify any positional parameters, then when you enter 
the alias on the command line, CodeProbe expands the alias and places 
the rest of the command line (the parameters), up to the end of line or 
to a semicolon, after the expanded alias. 

To include more than one command in the definition, you can do 
one of the following: 

□ separate the commands with the \ ; escape character. For example, 
the following alias assigns two commands, where and display to 
the alias tb: 

alias tb where\;d x 

□ enclose the definition in double quotes (" ") or braces ({}) and 
separate the commands with a semicolon (;), as follows: 

alias tb "wherejd x" 
alias tb {where;d x) 

If the definition contains double quotes, you must use braces or 
escape the quotes (by using \ " ). 

To continue the definition to another line, enter a backslash (\) at the 
end of the current line. 

Alias names are only expanded when they occur at the beginning of 
a command line. 

For example, you can define the print, look2, and printgo 
aliases as follows: 

alias print display 

alias look2 "g $1; where; g $2; where" 

alias printgo {print "vars: ", $*; go) 

After defining these aliases, you could use them as follows: 

> look2 sort swap 
sort:\sort.c\sort 20 

1* In routine sort : \sort.c\sort 20 

2 Called from sort: \smain.c\main 13 (+0xC) 

3 Called from 0xC3162E 
sort:\swap.c\swap 5 

1* in routine sort: \swap.c\swap 5 
2 Called from sort : \sort . c\sort 26 (+0x12) 
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3 Called from sort:\smain.c\main 13 (+0xC) 

4 Called from 0xC3162E 

> print tmp 
10 (OxA) 

> dw x 

0036c4a4 : 0000 0001 

> go sort 

> printgo i, p[i] 

vars: 0 (0x0) 0 (0x0) 

Program exited with code 0. 

The alias definitions in the previous example expand to the following 
commands: 

display tmp 
dump *y hex 2 

g sort; where; g swap; where 
display "vars: ", i, p [ i ] ; go 

If at least one parameter is specified in a definition, all unused 
parameters in the command line are discarded when the alias is 
expanded. If the definition contains one or more parameters, but the 
command line does not, the result is an empty expansion. For example, 
if you define look 2 as shown previously and then enter the following 
command lines: 

look2 fund func2 fund 
look2 fund 

these command lines are expanded as follows: 

g fund; where; g func2; where 
g fund; where; g ; where 

You can nest aliases in the definitions of other aliases. If the 
debugger detects a circular reference between aliases, it expands the 
references until it detects the cycle. If an alias references itself, the 
reference is not expanded. For example, alias where where 
args does not cause an infinite loop. 

You can use aliases to redefine any CodeProbe command except 
alias and unalias. To reference a command that has been aliased, 
escape the command name with a backtick character (' ). For example, 



the following sequence defines aliases for the set and enter 
commands so that they function as they did in CodeProbe 
Version 5.10: 

alias set opt 
alias enter 'set 

Note: The backtick character is used to escape the set command. 

To remove an alias name from the debugger’s list of aliases, enter 
the unalias command followed by the alias name. To remove all 
aliases, specify an asterisk (*) as the alias name: 

unalias name 
unalias * 


Using Macros (define and undefine) 

The define command provides a more general macro text 
substitution facility than the alias command. You can use the 
define command to create new debugger macros. (To customize 
existing commands, you should use the alias command.) 

Using the debugger’s define command is much like using the C 
preprocessor’s # define statement. Macros are expanded anywhere 
within a line of text unless they are enclosed inside of double 
quotes (" "). CodeProbe does not expand macro definitions that have 
been escaped by a backtick character (' ). 

To define a macro, enter the define command as follows: 

define macro-name definition 

For example, to define a constant named PI, you could enter: 
define PI 3. 14159 

To define a macro that takes parameters, enter the define command 
with parameters enclosed in parentheses: 

define macro-name (parml ,parm2 ,...) definition 
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Specify the parameters using standard C syntax. For example, you 
could define the macro IS EQUAL as follows: 


define ISEQUAL(a,b) (a == b) 

You can then use this macro in debugger commands, such as 
display: 


> display ISEQUAL( 1 , 5 ) 

0 (0x0) 

You can use the expand command to display a macro with its 
arguments expanded: 


> expand ISEQUAL( 1 , 5 ) 
(1 == 5) 


To display a list of all currently defined macros, enter the define 
command by itself: 


> define 
IS EQUAL 
PI 

memcmp(v1 ,v2,n3) 
memcpy(v1 ,v2,n3) 
memmove(v1 , v2,n3) 


(a == b) 

3.14159 

builtin_memcmp( vl f v2,n3) 

builtin_memcpy( vl , v2,n3) 

builtin_memmove( vl , v2,n3) 


(CodeProbe provides several built-in functions. These functions are 
discussed in Chapter 9, “Command and Built-in Function Reference.”) 
To define a symbol to nothing, omit the definition parameter as 
shown in the following example: 


define NUTIN 



Unlike the C preprocessor, the debugger treats define as a 
command, meaning that it stops parsing the define command when 
it reaches a semicolon (;). To include a semicolon as part of a 
definition, precede it with the backslash (\), as follows: 

\ ; 

To remove a macro definition from the debugger’s list of macros, 
enter the undefine command followed by the macro name. To 
remove all macros, specify an asterisk (*) as the macro name: 

undefine name 
undefine * 


Note: You cannot remove symbols generated by the compiler. 
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Introduction 

This chapter contains an example of debugging a C program. The 
example program is in the sc : example s/csource directory. This 
directory contains three files: 

smain . c 

defines an array of 10 integers, and calls functions in sort . c to 
initialize, sort, and print the array. 

sort . c 

defines the functions init, sort, and printArr. This file 
contains logic errors. The instructions in this chapter show you 
how to use CodeProbe to find the errors, 
swap. c 

contains a routine that accepts pointers to two integers and switches 
the integers. 

Appendix 2, “Source Code for Debugger Examples,” contains the 
source code for these files. 


Running The Example 

To compile and link this example, you can click on the Build icon in 
the sc : examples /c source directory, or you can change to that 
directory and compile the examples from the Shell: 

cd sc:examples/csource 

sc debug=symbolf lush link sort.c smain. c swap.c 
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The compiler creates an executable named sort in the 

sc : examples /c source directory. To run the program from the 

Shell prompt, enter: 

sort 

The program first defines and initializes an array of 10 integers. Then, 
the program is supposed to sort the array in descending order, and 
print the array. However, sort prints the following: 

array[ 1] is 8 
array[2] is 8 
array[3] is 8 
array [4 ] is 8 
array[5] is 8 
array[6] is 8 
array[7] is 8 
array[8l is 8 

sort is not printing all of the array elements, and it does not appear 
to be initializing the array correctly. 


Debugging The Example 

To run sort under the control of the debugger, you do one of the 
following: 

□ click once on the Debug icon, and then hold down the Shift key and 
double-click on the icon for the sort executable. 

□ enter the cpr command at the Shell prompt: 

cpr sort 


CodeProbe executes up to the first line of smain, as shown in Display 
3.1. 
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Display 3.1 

CodeProbe Windows 
Showing the sort 
Program 



To find out why sort is not printing all of the array elements, go to 
the printArr function. 

> go printArr 

CodeProbe stops at the first executable line of printArr. The line 
that is highlighted in the Source window is the line that is about to be 
executed. CodeProbe stops at: 

ptr = arrayPtr; 

You can now use the display command to test whether the size of 
the array is passed correctly into the function printArr: 


> d size 
10 (OxA) 


oqd: 
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The printArr function receives the correct number of array 
elements. To find out why printArr is not printing the last element 
of the array, execute up to the point where it should print the last 
element: 

> go 4 4 when(i == 8) 

sort:\sort.c\printArr 44 

The next line to be executed is the printf statement for 
arrayPtr [ 8 ] . You need to step past the printf statement. You can 
step one statement by entering the proceed command, and the easiest 
way to execute proceed is to simply press the Enter key. Any time 
you press the Enter key without typing anything on the command line, 
CodeProbe always executes the proceed command. If the current line 
is a function call, proceed executes the function as if it were a single 
statement. 

Press Enter twice, and then display the value of i: 

> d i 

9 (0x9) 

sort should execute the printf statement for arrayPtr [ 9 ] next. 
Press Enter and watch which line CodeProbe jumps to. CodeProbe 
jumps to line 45, skipping the printf statement, because the 
condition on the for loop prevents the loop from executing when i is 
equal to s i z e - 1 , which is now 9 . 

In the C language, arrays are indexed starting with zero, not 1, as in 
other languages such as Pascal. Before you can fix the error, you need 
to run your program to completion and exit the debugger: 

> go 

Program exited with code 0. 

> quit 

Edit the sort . c file, and change the for loop in the printArr 
function on line 43 to read: 


for (i=0; i < size; i++) 
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Then, compile the example as described under “Running The 
Example.” Run the program again: 

array[0] is 8 
array[1] is 8 
array[2] is 8 
array[3] is 8 
array [ 4 ] is 8 
array[5] is 8 
array[6] is 8 
array[7] is 8 
array[8] is 0 
array[9] is 0 

The program is now printing all of the elements of the array, but they 
do not appear to be getting initialized correctly. 

Restart CodeProbe with the new executable module: 

cpr sort 

CodeProbe stops at the call to init. Press Enter once to execute the 
init function. Now, display the array: 

> d array 

You can only see part of the array in the Dialog window, but you can 
use the Zoom function key to see the entire display. To zoom the 
Dialog window, press the F2 key. 
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Display 3.2 
Dialog Window In 
Zoom Mode 



As expected, the display shows that init is not initializing the array 
correctly. 

To redisplay the Source and Dialog windows in normal mode, press 
the F2 key again. 
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Display 3.3 
Source and Dialog 
Windows Showing 
Initialized Array 



To determine why init is not initializing the array correctly, you 
need to step into the init function, but you have already executed 
past init. You can restart the sort, but before you restart any 
program, you need to allow it to run to completion. When you restart 
a program, it is immediately reloaded and re-executed with no cleanup 
other than calling the exit function to close files. The machine may 
be left in a state that can cause problems later. To avoid this problem, 
allow your program to run to completion before restarting it. 

To run sort to completion and restart the program, use the go and 
restart commands: 

> go 

Program exited with code 0. 

> restart 

Starting "sort " 

sort:\smain.c\main 11 

The next line about to be executed is the call to the init function. 
Use the trace command to step into the init function: 

> t 

sort:\sort.c\init 10 
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The trace command works like the proceed command, except that 
if the current line is a function call, trace steps into the function 
instead of executing the function as if it was a single statement. 
CodeProbe displays the source code for init, as shown in Display 
3.4. 


Display 3.4 
Source Window 
Showing init 



In the Source window, you can see that the program contains the 
same mistake as before. The for loop specifies the wrong conditions. 
As before, you need to run your program to completion and exit the 
debugger: 


> go 

Program exited with code 0. 

> quit 

Edit the sort . c file, and change the for loop in the init function 
on line 11 to read: 


for ( i=0 ; i < size; i++) 
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Then, compile the example as described under “Running The 
Example.” Run the program again: 

array[0] is 9 
array[ 1 ] is 9 
array[2] is 9 
array[3] is 9 
array [ 4 ] is 9 
array[5] is 9 
array[6] is 9 
array[7] is 9 
array [ 8 ] is 9 
array [ 9 ] is 9 

Restart CodeProbe again: 

cpr sort 

Press Enter to execute the init function, and then display the 
initialized array: 

> d array 

( 

[0] = 0 (0x0) 

[1] = 1 (0x1) 

[2] = 2 (0x2) 

[3] = 3 (0x3) 

[4] = 4 (0x4) 

[5] = 5 (0x5) 

[6] = 6 (0x6) 

17] = 7 (0x7) 

[9] = 8 (0x8) 

[9] = 9 (0x9) 

} 


Press Enter again to execute the sort function, and then display the 
array again: 

> d array 

( 

[0] = 9 (0x9) 

[1] = 9 (0x9) 
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[21 

= 9 

(0x9) 

[31 

= 9 

(0x9) 

m 

= 9 

(0x9) 

[51 

= 9 

(0x9) 

[6] 

= 9 

(0x9) 

[71 

= 9 

(0x9) 

191 

= 9 

(0x9) 

[91 

= 9 

(0x9) 


) 

Either the sort function or a function called from sort is 
incorrectly changing the values in the array. You need to step into the 
sort function, but you have already executed past sort. Run the 
program to completion, and restart the debugger: 

> go 

Program exited with code 0. 

> restart 
Starting "sort " 
sort : \smain.c\main 11 

Go straight to the sort routine: 

> g sort 

sort:\sort.c\sort 22 


Use the ps command to go to the beginning of the for loop, and 
display the first two elements of the array: 


> ps 3 

sort:\sort.c\sort 23 
sort:\sort.c\sort 25 
sort:\sort.c\sort 25 (+0x2) 

> d arrayPtr [ 0 ) 

0 (0x0) 

> d arrayPtr ( 1 ] 

1 (0x1) 
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Press the Enter key 5 times until CodeProbe goes through the loop and 
reaches the for statement again. Then, redisplay the first two 
elements of the array: 

> d arrayPtr[0] 

1 (0x1) 

> d arrayPtr ( 1 | 

1 (0x1) 

Execute the for loop one more time: 


> ps 5 

sort: \sort .c\sort 26 
sort : \sort .c\sort 28 
sort: \sort .c\sort 29 
sort:\sort.c\sort 30 
sort:\sort.c\sort 25 


(+0x2) 


To exit the loop early, you can change the value of the loop counter 
so that the loop is not executed again. Use the set command to 
change i to 10, and then press Enter again: 


> set i= 1 0 

> 

sort:\sort.c\sort 32 


CodeProbe jumps to line 32. 

You want to display the array again, but you cannot use the d 
array command while you are inside the sort function, because 
array is not declared inside sort. You want to be able to display the 
array elements without having to exit the sort function or enter 
different commands for each element. 

You cannot remember if the dump command will do what you need. 
You can display the main debugger Help window by pressing the Help 
key. Display 1.3 in Chapter 1 shows the main CodeProbe Help 
window. 

To display specific information on a command, click on the name of 
the command. Display 3.5 shows the Help window for the dump 
command. 
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Display 3.5 

Help Window for 
dump Command 



You want to display a range of memory, so click on the range 
parameter. The Help window shows you two ways to specify the range: 

start-address . . end-address 
start-address L length 

To exit the Help window, click on the Close gadget in the upper left 
corner. 

The starting address of an array is the address of its first element, so 
you can specify arrayPtr in the dump command. By default, the 
dump command displays memory in hexadecimal notation, but you can 
display memory in decimal notation by specifying the decimal option. 
Also, since di is an alias for dump decimal, you can display the 
array as follows: 

> di arrayPtr L 10 
07D3E048: 1 2 

07D3E058: 4 5 

07D3E068: 8 9 

Note: The hexadecimal numbers at the left are the starting 
addresses of the first, fifth, and ninth elements of the array, 
respectively. These numbers may differ on your machine. 


2 3 

6 7 
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This time, array elements one and two are 2. You want to watch 
these array elements as they are changed, from the start of the sort. To 
go back to the start of the sort function, restart the debugger as 
usual: 

> go 

Program exited with code 0. 

> restart 
Starting "sort " 
sort:\smain.c\main 11 

Set a breakpoint at the beginning of the for loop in sort, and 
execute the program to that breakpoint: 

> break sort 25 

> go 

sort:\sort.c\sort 25 
Display the array again: 

> di arrayPtr L 10 

07D3E048 : 0 

07D3E058: 4 

07D3E068: 8 

Now that you have set a breakpoint, every time you enter go, the 
program will stop at that breakpoint. 

You can use the command line editing keys to re-enter the dump and 
go commands without having to retype them. You can press the Up 
Arrow (|) key to cycle through the commands that you have entered in 
the current session. When CodeProbe displays the command that you 
want to execute, simply press Enter. You can also edit the command 
before pressing Enter. For a complete description of command line 
editing functions, see Chapter 1, “Getting Started.” 

Use the command line editing keys to execute the for loop, and 
display the array again: 

> go 

sort:\sort.c\sort 25 

> di arrayPtr L 10 

07D3E048: 1 234 

07D3E058: 5 678 

07D3E068: 9 9 


1 2 3 

5 6 7 

9 
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You can use the Memory window to display the array as it changes. 
Open the Memory window using the window command: 

> window memory 

You can also open the Memory window by selecting Memory from the 
View pull-down menu. CodeProbe opens the Memory window in the 
top left corner of the screen, but you can move and resize this window 
just like Workbench windows. 

By default, CodeProbe displays memory beginning at the address 
stored in register A4. To display the memory where the array is 
stored, use the left button on the mouse to highlight the starting 
address of the array as displayed in the Dialog window. In this 
example, the starting address is 07D3E048. Then, click on the Goto 
gadget (>) in the Memory window. The first five lines in the Memory 
window should now display the contents of the array, as shown in 
Display 3.6. 


Display 3.6 

Memory Window 
Showing Array 
Contents 



To see the values of the array change as the program executes, enter 
the go command four times. The values in the Memory window 
change with each iteration of the for loop. 
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Display 3.7 

Memory Window 
Showing Changed 
Values 



The only code within the for loop that is changing the array is the 
call to the swap function. You need to step into the swap routine. You 
have not executed past swap yet, so you do not need to restart the 
debugger. Enter the go command: 

> go swap 

sort : \swap.c\swap 5 
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Display 3.8 

Source Window 
Showing swap . c 



The sort routine should be a simple bubble sort, which means that the 
logic should be: 


temp = a; 
a = b; 
b = temp; 


In swap, c, lines 5 and 6 are reversed. 

You need to clear the breakpoint, run the program to completion, 
and exit the debugger, so that you can edit swap . c and fix the error. 


> be * 

> go 

Program exited with code 0. 

> quit 
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Edit the swap . c file, and change the swap function to read: 

void swap(int *x, int *y) 

{ 

int tmp; 

trap = *x ; 

*x = *y; 

*y = tmp; 


Then, compile the example as described under “Running The 
Example.” Run the program again: 

array[0] is 9 
array [ 1 ] is 8 
array[2] is 7 
array[3) is 6 
array[4] is 5 
array[5] is 4 
array[6] is 3 
array! 7] is 2 
array[8] is 1 
array[9] is 0 
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Introduction 

This chapter contains an example of debugging a C + + program. The 
example program is in the sc : examples /cxx directory. This 
directory contains two programs: 

chess 1 . cxx 

is a basic chess program that declares two classes: chessPiece 
and chessBoard. The chessPiece class describes the pieces 
used in a game of chess. The chessBoard class describes the 
board on which the chess pieces are placed and moved. The 
chessBoard class contains a data member, board, which is an 
array of pointers to chessPiece objects. 

chessl .cxx contains a logic error. The instructions in this 
chapter show you how to use CodeProbe to find the error. 
chess2 . cxx 

contains a corrected version of chess 1 . cxx. You can compile, 
link, and run chess2 . cxx if you want to see what chess 1 . cxx 
should print after you have fixed its logic error. 

Appendix 2, “Source Code for Debugger Examples,” contains the 
source code for chess 1 .cxx. 


Running The Example 

To compile and link this example, enter the following command at the 
Shell prompt: 


sc debug=ff pname=chess link sc:examples/cxx/chess1 .cxx 
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Display 4.1 

Initial Results of 
chess 


This command creates an executable module named chess in your 
current directory. To run the program from the Shell prompt, enter: 

chess 

The program first instantiates a chessBoard object called 
gameboard. The chessBoard constructor then instantiates the 
appropriate chessPiece objects needed in a chess game. Each 
position in the chessBoard object’s 8x8 array points to the correct 
chessPiece object at the start of a chess game. 

Next, the program starts the game with the Sicilian opening and 
displays the chess board. However, the pieces that were moved are 
moved to the wrong sides of the chess board, as shown below. 



Finally, the gameboard object is a local object to the function 
main, so its scope ends when function main returns, board is a 
chessBoard object, so it is destructed when the program ends. The 
chessBoard destructor frees all of the chessPiece objects to 
which its data member board points. 
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Debugging The Program 

To run chess under the control of the debugger, enter the cpr 
command at the Shell prompt: 

cpr chess 

Since the chess program is setting up the board correctly, but 
pieces are being moved to the wrong places, the error is probably in 
the chessBoard: imovePiece function. For C+ + programs, you 
can identify a member function by specifying its class and name 
separated by a double colon: 

> break chessBoard: :movePiece 

Now, run the program until it encounters the breakpoint: 

> go 

CodeProbe stops at the first line of the chessBoard: imovePiece 
function. 

First, display the coordinates from which the next piece will be 
moved: old_r and old_c: 

> d old_r 
1 (0x1) 

> d old_c 
4 (0x4) 

In the Sicilian opening, the first move is Pawn to King 4 (P-K4). Since 
white always moves first, the piece that is moved should be the white 
pawn. You want to verify that the piece identified at these coordinates 
is the white pawn. 

To display the contents of any class data member within a member 
function, treat the data member like a global variable. CodeProbe uses 
the this pointer to display the data member of the correct object. To 
find out what piece will be moved, enter the following display 
command: 


> d *board[ 1 ] [ 4 ] 



CodeProbe prints the data members of the chessPiece object 
pointed to by board [ 1 ] [ 4 ] : 


struct chessPiece { 
name = "pawn\0" 
color = 'w' 119 (0x77) 
code = * P ' 80 (0x50) 
value = 1 (0x1) 

) 


You now know that the correct piece will be moved, so execute the 
program until the chess piece has been moved from its old position to 
its new position. The code that moves the chess piece is: 

board [ new_c ) [new_r] = board [ old_r ] [old_c] ; 

To execute chess past this line, you enter: 

> ps 4 

The coordinates of the pawn’s new position should be 
board [ 3 ] [4]. To verify that the correct coordinates are passed into 
chessBoard: :movePiece, display the values of new_r and 
new_c: 

> d new_r 

3 (0x3) 

> d new_c 

4 (0x4) 

These coordinates are correct. To determine if the white pawn was 
moved to position board[3] [4], enter the display command: 

> d *board[ 3 ] [ 4 ) 

" attempt to dereference null pointer 

This position on the board is NULL. The white pawn was moved 
somewhere else. You need to find out where the white pawn was 
moved to. 
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First, delete the current breakpoint, run the program to completion, 
and restart the chess program: 

> be * 

> go 

Program exited with code 0. 

> restart 
Starting "chess" 

chess : \t: chess . .c\main 115 


Then, set a breakpoint in chessBoard: imovePiece that stops the 
program when color is w and code is P. Use the slash (\) character 
to continue the command line: 


> break chessBoard: :movePiece \ 

>> when ( board [old_r ] [old_c]->color == 'w' SS \ 

» board [ old_r ] [old_c]->code == ' P ' ) 

Use the go command to execute the program up to the breakpoint: 


> go 

chess:\t:chess1 . .c\movePiece_10chessBoardFiiii 90 

You can find out what position the white pawn is being moved to by 
displaying the values of new_r and new_c again: 


> d new_r 

3 (0x3) 

> d new_c 

4 (0x4) 


The coordinates to which the white pawn was supposed to have been 
moved are correct, but the instruction that uses these coordinates uses 
them in reverse order. The white pawn should be moved to 
board [ 3 ] [ 4 ] , not board [ 4 ] [ 3 ] , which indicates that the 
assignment statement shown previously is incorrect: 


board [ new_c ] [ new_r ] = board [ old_r ] [ old_c ] ; 
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Display 4.2 

Final Results of 
chess 


Before you can fix the error in the program, you need to clear the 
breakpoint, run the program to completion, and then quit the 
debugger. 


> be * 

> go 

Program exited with code 0. 

> quit 

Edit the chessl .cxx file, and change the assignment statement on 
line 90 in chessBoard: imovePiece to read: 


board [ new_r ] [new_c] = board [ old_r ] [old_c] ; 

Then, compile the example as described under “Running The 
Example.” Run the program again. Now the board prints correctly. 
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Introduction 

You can use CodeProbe to debug your own shared libraries. 
CodeProbe allows you to 

□ set breakpoints in the library 

□ use the symload command to read symbol information from a 
library executable file 

□ use the libraries. cpr AREXX macro to display the libraries in 
the system. 

□ trace into a call to a shared library. 

The last section in this chapter contains an example of debugging a 
shared library. 


Setting Breakpoints 

You can set breakpoints in any shared library that your program may 
use. For example, the following command sets a breakpoint on the 
function myfunc in library mylib. library: 

break mylib. library :myfunc 

If your program has not yet called OpenLibrary to open 
mylib . library, then CodeProbe waits to install the breakpoint until 
the library has been opened. When CodeProbe detects that the library 
has been opened, it loads the debug information for that library. If 
myfunc does not exist, or if it cannot find the debug information for 
that library, CodeProbe stops the program at that point and gives you 
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a message. You can then specify a different function or use the 
symload command to load debug information from a different 
location. 

► Caution Incorrect use of breakpoints may crash your machine. 

A breakpoint is implemented by placing an illegal instruction at the 
desired location. All tasks under the debugger’s control have a trap 
handler that reports back to the debugger when the illegal instruction 
is executed. If you must place a breakpoint in shared code, such as a 
resident library under test, be sure that any task that might open the 
library is under debugger control. If another process is also using the 
same library, it will cause a crash when the program encounters the 
illegal instruction. Never place breakpoints in libraries that you do not 
control. ▲ 

Loading Debug Information (symload) 

You can use the symload command to load debugging information for 
a shared library, if that library was compiled with one of the debug 
options. For example, the following command loads debugging 
information for the library named my lib. library located in the 
current directory: 

symload mylib. library 

See Chapter 9, “Command and Built-in Function Reference,” for a 
complete description of the symload command. 


Displaying the List of Loaded Libraries 
(libraries.cpr) 

You can use the libraries.cpr AREXX macro to display a list of 
the libraries that are currently loaded. To run this macro, enter 
libraries on the command line of the Dialog window, libraries 
displays information in the following format: 

Address NT Pri Open Name 
$07DC 1220 900 "scxx . library" 

$07D7 1 0 1C 9 0 0 "amigaguide. library" 
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These fields contain the following information: 

Address contains the address of the library base. 

NT indicates the type of node that begins the exec node. 
The number 9 is used for libraries. For a complete list 
of the possible node types, see the header file 
include : exec /nodes . h. 

Pri contains the priority of the library node. 

Open indicates the current open count of the library. 

Name is the name of the library as specified in the library 
itself. 


See Chapter 7, “Using AREXX Macros with CodeProbe,” for more 
information about AREXX macros in general. 


Tracing Into A Shared Library 

To trace into a shared library, make sure that the Step into 
Res lib? option is set to on. Then, use the trace command to step 
into the library, just as you would with an ordinary function call. 


Debugging UserLiblnit and UserLibCleanup 

To debug UserLiblnit, follow the same procedure as for debugging 
devices. To debug UserLibCleanup, simply set a breakpoint in it. 


Example 

The sc : examples /res lib directory contains an example of a 
shared library: 

my lib . c 

contains the source code for the shared library, 
mylib . f d 

is the function description file that slink uses to create the shared 
library. 

mylib_pragmas . h 

contains the prototypes and # pragma statements for the two 
functions in the library: testl and test 2. 
test . c 

contains a short program that opens the library mylib, calls 
testl and test 2 , and closes the library. 



smakef ile 

contains the sc and slink commands required to create the 

library and compile test . c. 

Appendix 2, “Source Code for Debugger Examples,” contains the 
source code for mylib . c, mylib . f d, and test . c. 

To create and debug the shared library mylib, follow these steps: 

1. Build the library. If sc : examples /res lib is your current 
directory, you can enter smake at the Shell prompt. From the 
Workbench, you can double-click on the Build icon. 

smake builds the library mylib. library and installs it in 
your LIBS : directory, smake also builds the program test in 
the current directory. 

2. Run the test program under the debugger. If 

sc : examples /res lib is your current directory, you can enter 
cpr test at the Shell prompt. From the Workbench, you can 
click once on the Debug icon, hold down the Shift key and 
double-click on the test icon. 

3. Tell CodeProbe that you want to debug shared libraries. You can 
either enter the opt res lib on command in the Dialog 
window, or use the mouse to select the Step into Res lib? 
menu item from the Options pull-down menu. 

4. Set a breakpoint in the library routine and proceed. Enter the 
following commands in the Dialog window: 

b mylib. library :LIBtest1 
go 

After entering go, CodeProbe stops at the function testl in the 
library. The LIB prefix is determined by the libprefix option 
specified in the slink command that creates the library. This 
prefix may vary for your own libraries. Specify this prefix for 
functions that are listed in your . f d file only. 

5. Enter debugger commands as if you were debugging a normal 
program. Anything you can do in the debugger under normal 
circumstances is legal in the shared library. For example, you can 
set the value of the external variable b: 

set b = 10 
go 


The debugger stops at the breakpoint again. 
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6. Press the F9 (Swap) key to display the Output window for the 
test program. The Output window contains the message: 

Library Opened Successfully 
testl returned = 10 

Note: When debugging a shared library, you cannot examine 
global variables declared in modules outside the library even if 
you specify the full pathname of the module. 

7. Press F9 again to return to the Dialog and Source windows. 

8. Clear all breakpoints and allow the program to run to completion. 

be * 
go 

The test program calls the AmigaDOS Delay function, so 
under both AmigaDOS 1.3 and 2.0, there is a short delay before 
the program completes. Under AmigaDOS 2.0, you will have to 
go to the workbench and click on the close gadget of the program 
before the window will close. 

9. Terminate the debugger by entering the quit command. 
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Introduction 

CodeProbe has special commands that allow you to debug applications 
that spawn tasks. An application can spawn two types of tasks: 

synchronous 

Synchronous tasks are created, run to completion, and then return 
control to the parent process while the parent process waits. You 
should debug synchronous tasks as separate programs before 
debugging the parent process. The multitasking commands and 
examples described in this chapter do not apply to debugging 
applications that spawn synchronous tasks. One way a program can 
spawn a synchronous task is by calling the system function with 
your executable module as a parameter. 
asynchronous 

When a parent process spawns an asynchronous task, control 
returns to the parent process immediately after the task is created. 
The two tasks then run independently, and both are under debugger 
control. This chapter describes the multitasking commands that you 
can use to debug applications that spawn asynchronous tasks. One 
way a program can spawn an asynchronous task is by calling the 
forkv, forkl, or CreateNewProc functions with your 
executable module as the first parameter. 



How CodeProbe Handles Tasks 

CodeProbe debugs multitasking applications by intercepting every call 
to AddTask and determining the identity of the calling task. If the 
calling task is under debugger control and the catch option is set to 
on, the new task is also brought under debugger control. You can stop 
any task under CodeProbe’s control by setting a breakpoint or by 
single stepping. Also, if you enter Control-C in the Dialog window 
while an application is running, all active tasks under debugger control 
are stopped. 

CodeProbe implements breakpoints by placing an illegal instruction 
at the desired location. To handle these illegal instructions, CodeProbe 
redefines the task’s trap handler so that it catches the illegal 
instruction and reports back to the debugger. 

If several tasks are running under the debugger’s control when a 
breakpoint is reached, all other tasks on the debugger’s list are stopped 
as well as the one that encountered the breakpoint. Therefore, the state 
of the application remains consistent while you examine the task. The 
debugger sets the environment to that of the breakpoint task. That is, 
the current module, current line, and the registers displayed all belong 
to the breakpointed task. The name and address of the Task Control 
Block for the current task are always displayed in the Dialog window’s 
title bar. 

To control multitasking, CodeProbe performs a SetFunction on 
the AddTask, OpenLibrary, OpenDevice, and RemTask 
functions. Do not redefine these functions in your application. 


Redefining Exception and Trap Handlers 

To establish breakpoints and catch new tasks generated in a 
multitasking application, CodeProbe manipulates certain resources in 
the application’s task structure. Specifically, CodeProbe redefines a 
task’s exception handler, exception data, trap handler, and trap data 
fields. If you redefine any of these fields in your application, redefine 
them as described in the Amiga ROM Kernel Reference Manual: 
Libraries and Devices. 

Exception handlers must save the address of the original exception 
handler and exception data fields and pass any unallocated exceptions 
back to the original exception handlers. Before invoking the original 
exception handler, restore the original exception data pointer in the 
task structure. 
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Trap handlers must also save the address of the original trap 
handler and trap data field and pass any unallocated traps back to the 
original trap handlers. Before invoking the original trap handler, 
restore the original trap data pointer in the task structure. 


Commands for Debugging Multitasking 
Programs 

CodeProbe provides several commands that you can use to debug 
multitasking applications, including: 

tasks 

displays a list of the tasks currently under debugger control. If you 
specify tasks all, this command displays the list of all system 
tasks. 

opt task 

displays the current task or, if you specify a task name or address, 
changes the current task to the task you specify. If you switch to a 
task that does not have debugging information, the task is probably 
in an operating system routine (probably Wait), 
deactivate 

prevents a task from running, even when a go or proceed 
command is executed, unless the task is the current task, 
activate 

reactivates a task that was deactivated with the deactivate 
command, 
detach 

frees a task from debugger control, 
catch 

places a task under debugger control, 
symload 

loads debugging information for the executable file that you specify. 

Chapter 9, “Command and Built-in Function Reference,” describes 
each of the commands in detail. 



Example: Debugging a Child Process 

The sc : examples/multitask directory contains the following 
files: 

process . c 

defines the functions process_starter, start-process, and 
wait— process, 
test . c 

defines process 1 and a main program that uses the functions 
defined in process . c. 

Appendix 2, “Source Code for Debugger Examples,” contains the 
source code for these files. 

test . c starts a new process that executes in the same code hunk as 
the parent process. This type of task is the easiest type of multitasking 
program to debug because CodeProbe has all of the debugging 
information for both tasks when the parent process starts. 

To compile and link process. c and test . c, double-click on the 
Build icon, smake creates an executable named test. To run the 
debugger on test, follow the instructions in the list below. 

Note: These instructions assume that Enforcer is not running on 
your machine. If Enforcer is running, CodeProbe will detect an 
Enforcer hit during step 5. 

1. Invoke CodeProbe on the test program. From the Workbench, 
you can click once on the Debug icon and then hold down the 
Shift key and double-click on the icon for the test executable. 
From the Shell, if the sc : examples /multitask directory is 
your current directory, you can enter: 

cpr test 

2. Tell the debugger to catch new tasks: 


opt catch on 
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3. Set a breakpoint at the function that will be executed as part of 
the child process, and then run the program: 

break process 1 
go 

CodeProbe stops when it encounters the breakpoint on line 1 of 
process 1. 

4. Enter the tasks command to list the processes now under 
CodeProbe’s control. 

tasks 

CodeProbe now controls two tasks. 

The next line of process 1 does an Open on CON:, which 
starts a new task, but you do not want CodeProbe to catch that 
task. 

5. Use the opt catch command to turn off the catching of new 
tasks, and then run the program: 

opt catch off 
go 

test will open a window and print the message Hit Return 
to Close Window. 

6. Press the F9 (Swap) key to switch to the Output window. 

7. Press Enter to close the window. The test program then runs to 
completion, and CodeProbe displays the message Program 
exited with code 0. 

8. Quit the debugger: 

quit 


Example: Finding Enforcer Hits In Child 
Processes 

Note: These instructions assume that your machine is equipped 
with an MMU to run Enforcer. If you do not have an MMU, go to the 
next example. This example uses the same files as the preceding 
example: process . c, test . c, and process . h. 

The process 1 function in test . c contains code that generates an 
Enforcer hit. processl is executed as the child process. The 



following instructions are the same as those for the previous example, 
except that you do not set a breakpoint in process 1 . CodeProbe 
stops in processl when it encounters the Enforcer hit. The following 
instructions describe only those steps that differ from those listed 
under “Example: Debugging a Child Process.” 

If you have not already compiled and linked process. c and 
test.c, double-click on the Build icon, smake creates an 
executable named test. 

1. Start Enforcer, if it is not already running: 

enforcer 

2. Invoke CodeProbe on the test program. From the Workbench, 
you can click once on the Debug icon and then hold down the 
Shift key and double-click on the icon for the test executable. 
From the Shell, if the sc : examples /multitask directory is 
your current directory, you can enter: 

cpr test 

3. Tell the debugger to catch new tasks and then run the program: 

opt catch on 

go 

Whenever you enter go, CodeProbe runs all tasks under its 
control. If any task encounters a breakpoint or Enforcer hit, 
CodeProbe suspends all tasks. 

CodeProbe stops when it encounters the Enforcer hit in 
processl. The lines in processl that generate the Enforcer 
hit are: 

a = NULL; 

*a = 0; 

Note: Putting harmless Enforcer hits such as this in your 
program can help you debug multitasking programs. 

4. Follow the instructions for steps 4 through 8 of the example 
under “Example: Debugging a Child Process.” 
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Example: Catching Tasks That Are 
Already Running 

The sc : examples / cat ching_t asks directory contains these files: 
loop . c 

defines amain program that contains an infinite loop, 
dummy . c 

defines a main program that does nothing but return. 

Appendix 2, “Source Code for Debugger Examples,” contains the 
source code for these files. 

To compile and link loop . c and dummy . c, double-click on the 
Build icon, smake uses the information in the smakef ile to create 
two executables: loop and dummy. 

The next two sections describe how to catch tasks that are already 
running. The first section describes how to catch a task that was 
started from the Shell. The second section describes how to catch a 
task that was started from Workbench. 


Catching 
Processes 
Started from 
the Shell 


The following list describes how to start a process from the Shell and 
catch it with the debugger. 

1. Start a Shell. 

2. Change to the sc : examples/catching_tasks directory, and 
start the loop program. 


cd sc : examples/catching_tasks 
loop 

loop just prints out looping. . . over and over. (This program 
sets its priority to -1, so that it does not monopolize the CPU.) 

3. Switch back to the Workbench screen. 

4. Start the debugger on the dummy program, by clicking once on 
the Debug icon, then holding down the Shift key and double- 
clicking on the dummy icon. 

5. Tell the debugger to list all of the tasks in the system: 


tasks all 



6. Find the task with the priority of -1. If you are running the 
standard Shell under AraigaDOS 2.0, the name of the process will 
be Shell Process. If the name is unique, you can use the 
name to identify the process. If not, use the address in the first 
column to identify the process. Now catch the process: 

catch "Shell Process" 

If you specify the process name, enclose the name in double 
quotes, as shown. Alternatively, you can specify the process 
address in hexadecimal notation: 

catch 0 xnnnnnnn 

7. Now list the tasks under the debugger’s control: 

tasks 

8. Detach the dummy process, since you are not interested in 
debugging it. Use the address in the first column to identify the 
task. 

detach 0 xnnnnnnn 

nnnnnnn is the address of the process. 

CodeProbe displays assembly lines for the loop program. The 
debugger probably stopped loop in an operating system call. 

9. Load the debugging information for the loop program. Use the 
form of the symload command that uses the seglist from the 
CLI structure: 

symload "loop" 

10. Set a breakpoint in the loop program, and then run the 
program: 

break loopzmain 18 
go 


CodeProbe stops the program on line 18. 



Debugging Multitasking Programs 87 


11. You can set i to 1, and press Enter 3 more times to exit the 
loop: 

set i = 1 
proceed 
proceed 
proceed 

12. Quit the debugger: 

quit 


When you enter the quit command, the debugger releases all 
captured tasks, and they run normally until completion. The main task 
(dummy, in this case) is not allowed to run to completion. CodeProbe 
forces it to call exit, if appropriate, and then CodeProbe terminates 
the task. For more information, see the description of the quit 
command in Chapter 9, “Command and Built-in Function Reference.” 

If you enter the go command instead of entering quit for the last 
step, CodeProbe will not return control to you. The Shell Process does 
not terminate; only the loop program terminates. The Shell Process is 
now running the Shell, and CodeProbe is actually debugging the Shell. 
At this point, you can press Control-C and then enter quit. The Shell 
should then run as normal. 


Catching 
Processes 
Started from 
Workbench 


The only difference between catching a process started from the Shell 
and one started from Workbench, is determining the name of the 
process. The name is usually the name of the executable module. For 
our example, the name of the process is loop. 

The following list describes only the steps that differ from those 
listed under “Catching Processes Started from the Shell.” 


1. Open the sc : examples/catching_tasks directory, and 
double-click on the loop icon, loop just prints out 
looping . . . over and over. (This program sets its priority to 
-1, so that it does not monopolize the CPU.) 

2. Start the debugger on the dummy program, by clicking once on 
the Debug icon, then holding down the Shift key and double- 
clicking on the dummy icon. 

3. Tell the debugger to list all of the tasks in the system: 


tasks all 
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Debugging 
Devices That Do 
Not a Create 
New Task 


4. Find the task with the name loop. Catch this process: 

catch "loop" 

5. Follow steps 6 through 10 of the instructions listed under 
“Catching Processes Started from the Shell.” Do not enter quit 
as instructed in step 11. The loop program was started from 
the Workbench, not the Shell, so its process terminates when the 
loop program finishes. Therefore, you can use the go command 
to allow the program to run before quitting the debugger. 

6. Run the program to completion, and then quit the debugger: 

go 

quit 


Example: Debugging Devices 

The remainder of this chapter describes how to debug: 

□ devices that do not create a new task 

□ a task created by a device 

□ the Open, Init, or UserDevlnit functions in a device. 

Debugging a device that does not create a new task is exactly like 
debugging a shared library. For example, you could set a breakpoint 
on a function DevBeginlO in the device example .device by 
entering: 

break example. device:DevBeginIO 

See Chapter 5, “Debugging Shared Libraries,” for more information. 

Note: CodeProbe does not have any debug information for the 
device until the OpenDevice call has returned. Therefore, you cannot 
use this syntax to set breakpoints in the Init, Open, or 
UserDevlnit functions in a device. 

The last section of this chapter, “Debugging the UserDevlnit Routine,” 
describes how to use Enforcer and SegTr acker to debug the 
UserDevlnit function of the example program that is described in 
the next section. 
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Debugging 
Tasks Created 
by a Device 


The sc : examples/example_device directory contains these files: 
serial . c 

defines the device example-device. This file defines several 

functions, including cmd_handler, UserDevInit, and 

DevBeginlO. 
driver . c 

defines main program that uses example-device. 

Appendix 2, “Source Code for Debugger Examples,” contains the 
source code for these files. 

The driver .c program calls OpenDevice, which loads 
example .device, and starts a new task running in a separate code 
hunk from the original program. 

To compile and link ser ial . c and dr iver . c, double-click on the 
Build icon, smake creates executable files named driver and 
example . device, and copies example . device to your devs : 
directory. To debug example . device, follow the steps in the list 
below. 

Note: example . device runs only under AmigaDOS 2.0 or 

higher because it calls the CreateNewProc function. 

1. Invoke CodeProbe on the driver program. From the 
Workbench, you can click once on the Debug icon and then hold 
down the Shift key and double-click on the icon for the driver 
executable. From the Shell, if the 

sciexamples/exampl e_ d e v i c e directory is your current 
directory, you can enter: 

cpr driver 

The driver program calls OpenDevice. 

2. Tell the debugger to catch new tasks and to catch devices: 


opt catch on 
opt devices on 
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3. Set a breakpoint in the code for the new task: 

break example. device :cmd_handler 70 

When you are setting breakpoints in a device that executes as a 
new task, make sure that: 

□ CodeProbe has control of the task that encounters the 
breakpoint. As described earlier, CodeProbe implements 
breakpoints by inserting illegal instructions. If a task that is not 
under CodeProbe’s control encounters a breakpoint, the 
program gets a Software Error 4. 

□ You set the breakpoint at a location such that when the 
program counter reaches that location, CodeProbe has debug 
information for that process. When you are debugging a 
device, CodeProbe does not have debug information about the 
device until the OpenDevice function returns. 

For this example, line 70 of cmcLhandler is a safe 
location because line 69 waits for the first message to be sent 
to it from the BeginlO function. BeginlO is not called until 
after OpenDevice has returned. 

If you want to debug a location before line 70 or before the 
location where OpenDevice returns, you can use Enforcer 
and SegTracker as described in the next section. 

4. Run the program: 

go 

CodeProbe stops at line 70 of cmd_handler and displays the 
source code for serial . c. 

5. List the tasks under CodeProbe’s control: 

tasks 

CodeProbe currently controls four tasks. The two extra tasks 
were created by the Open of CON : on lines 58 and 60 of 
ser ial . c. 
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6. You do not want to debug the these tasks, so you can detach 
them: 

detach "CON" 
detach "CON" 

7. List the tasks again: 

tasks 

CodeProbe now controls only two tasks. At this point, you can 
continue debugging as normal. 

Debugging the If Enforcer and SegTracker are running on your machine, you can 
UserDevInit insert code that generates an Enforcer hit at the start of 
Routine UserDevInit. For example: 


( 

char *a = 0; 
*a = 0; 

} 


Then, run CodeProbe on the program that opens your device, and then 
run the program: 

cpr program-name 
go 

CodeProbe stops at the Enforcer hit and displays the assembly code for 
UserDevInit. OpenDevice has not yet returned, so CodeProbe 
does not have any debug information for the device. To load the debug 
information, enter: 


symload 



This form of the symload command asks SegTracker for the name 
and seglist of the current PC and loads the debug information. If the 
device load module is not in the current directory, you may need to 
use a different form of the symload command. 

symload PC pc "module-pathname" 

The module-pathname is the absolute path to the load module. Enclose 
the pathname in double quotes, as shown. 
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Introduction 

This chapter describes: 

□ the CodeProbe macros that are provided with the SAS/C 
Development System 

□ how to invoke AREXX macros in the debugger 

□ the status codes returned by debugger commands and how to use 
them in an AREXX macro 

□ how to access the output of debugger commands in an AREXX 
macro 

□ how to use the debugger’s AREXX port to send commands to 
CodeProbe and receive command output from outside of CodeProbe. 


Macros Provided with CodeProbe 

The sc : rexx directory contains several macros that you can invoke 
from inside CodeProbe. Some of these macros simulate commands 
supported by the Commodore debugger, wack. The following list 
describes the macros provided with CodeProbe. 

avail 

displays the amount of available memory. 

dbptr ( variable \ address \ range) 

dumps memory as bytes for the specified variable, address, or 
range. By default, dbptr dumps 64 bytes of memory. 

dbstr ( variable \ address \ range) 

dumps memory as bytes for the specified variable, address, or 
range, dbstr dumps the amount of memory associated with the 
variable, address, or range. 



devices 

displays the list of system devices. This macro displays the same 
information as the devs macro, 
devs 

displays the list of system devices. This macro displays the same 
information as the devices macro, 
execbase 

dumps exec base information, such as the processor type. For 
more information, see the file exec/execbase .h. 
ints 

displays the list of interrupt handlers, 
libraries 

displays the list of resident libraries. This macro displays the same 
information as the libs macro, 
libs 

displays the list of resident libraries. This macro displays the same 
information as the libraries macro, 
makeaptr 

converts a BPTR to an APTR. 
man function-name 

displays help information for the specified library function, 
memory 

displays regions of memory, 
mods 

displays the system resident modules, 
ports 

displays the list of public ports, 
regions 

displays regions of memory, 
resources 

displays the list of system resources. This macro displays the same 
information as the rsrcs macro, 
rsrcs 

displays the resources in the system. This macro displays the same 
information as the resources macro, 
showcli [hex-address] 

dumps the CLI structure for the specified command, process 
address, or task number. 
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showprocess [task-name \ hex-address] 

displays the process structure for the specified task name or task 
address. If you do not specify a task name or address, CodeProbe 
displays the current task, showprocess verifies that the specified 
task is a valid process before displaying the information. 

Note: showprocess may not always be able to find a task by 

name, 
status 

displays all CLI tasks, 
which is [command | hex-address | n] 

identifies the CLI process associated with the specified command, 
task address, or task number. 

All of these macros are in sc : rexx, and they have the filename 
extension . cpr. CodeProbe recognizes macros if they have the . cpr 
extension. 


Invoking Macros 

To invoke a macro from CodeProbe, enter the name of the macro (and 
any necessary parameters) from the command line. You do not need to 
enter the .cpr extension. CodeProbe looks for the macro in the 
following places: 

1. the current directory 

2. sc : rexx 

3. REXX:. 

For example, the following macro, named avail . cpr, uses the 
storage function to display the amount of memory available. 

/* */ 

'd II storage() 'bytes free"' 
exit(O) 

To invoke this macro, enter avail at the debugger command line. The 
display command in the avail . cpr macro displays the value 
returned by the storage function, and the string bytes free, as in 
the following example: 

> avail 

1953944 bytes free 



Using Debugger Command Return Codes 
in Macros 

CodeProbe commands provide return codes that you can use from 
inside AREXX macros. CodeProbe commands return status codes to 
A RE XX as follows: 


Return 

Code Explanation 

0 The debugger command was successful. 

1 The command was syntactically correct, but the program 
failed for some other reason. 

2 A syntax error occurred. 

3 The debugger could not allocate memory for the AREXX 
message. 


Status codes are returned in the variable rc. You can check this 
variable to determine if a CodeProbe command was successful. For 
example, the following lines display command successful if the 
opt command returns a status code of zero: 


/* */ 

'opt catch on' 
if (rc = 0) then do 

'd "command successful" 


Using Debugger Command Output in 
Macros 

In addition to command return codes, AREXX macros can receive the 
output of debugger commands as it would normally appear in the 
Dialog window by invoking the AREXX command options 
results. If the debugger command returned a zero status code, the 
command output is then accessible in the variable result. 
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For example, you can execute the display debugger command 
from outside the debugger as follows: 


/* */ 

options results 

'd A4 ' 

'd "register A4= 'result'"' 


The output from the CodeProbe command is assigned to the AREXX 
variable result. 


Using Macros from Outside of CodeProbe 

CodeProbe supports an AREXX interface through the SC_CPR port. To 
send debugger commands to CodeProbe in an AREXX macro from 
outside of CodeProbe, specify the port name with the AREXX 
address command: 

/* */ 

address "SC_CPR" /* only if macro was not */ 

. /* invoked from CodeProbe */ 
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Introduction 

Cross-debugging is the process of running your program on one Amiga 
system and debugging it from another Amiga system. Cross-debugging 
is useful for debugging a program that shuts down Intuition, partially 
takes over your machine, or uses graphics heavily. 

In cross-debugging mode, the cross debugger communicates with a 
small kernel that controls the application through a serial 
communications port or over a network using named pipes. 

This chapter describes how to debug your program in cross- 
debugging mode. 


Why Debug in Cross-Debugging Mode? 

The following list describes several situations in which you may want 

to debug in cross-debugging mode: 

□ It is easier sometimes to see and send input to both your program 
and the debugger if they have their own separate monitors and 
keyboards. 

□ Some applications use low-level graphics control, which takes control 
away from Intuition. Since the debugger’s windowing system is built 
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Establishing 

Communications 


Copying the 
Necessary Files 


on top of Intuition, you cannot communicate with it while such an 
application is running. 

□ With very large applications in tight memory situations, there may 
not be enough memory available for both CodeProbe and your 
application. The cross-debugger kernel that runs on the machine 
with the application is small (less than 3 OK) and allows the 
application to use most of the available memory. 

□ Disk space limitations may make it difficult to have the debugger, all 
the necessary source files, and a copy of the application with debug 
information on the same machine with all the files needed by the 
running application. 

□ If the program being debugged crashes, you can continue to work on 
the machine with the source code while it is rebooting. 


Preparing to Use Cross-Debugging Mode 

As stated previously, the cross debugger communicates with a small 
kernel that controls the application through a serial communications 
port or over a network using named pipes. The machine containing the 
source code and the cross debugger is called the host machine. The 
machine containing the kernel and on which your program runs is 
called the target machine. You enter debugging commands on the host 
machine. 

Before debugging your program, you must establish communications 
between the host and target machines. You also need to make sure that 
the necessary files are stored on each machine. 

To use the cross debugger, you need two Amiga machines. You can use 
a null modem cable to connect the machines, or you can debug over 
the phone, if both Amiga machines are connected to modems. You can 
also debug over a network. 

If you use the serial port, use the serial icon in the Preferences 
menu to select the highest baud rate acceptable. With a null modem 
cable, a baud rate of 19200 works fine. If you debug over the phone, 
specify the maximum baud rate accepted by your modems. If you 
debug over a network, use named pipes. 

Two files must be installed on the target machine: 

□ the kernel (CPRK). Simply copy it to the target machine. The 
location to which you copy the kernel is not important. 

□ the application program that is to be debugged. The application can 
be stripped of debug information. You can use the cross debugger to 
install your program on the target machine and strip the debug 
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information by specifying the -x option. For more information, see 
the description of the -x option in “Starting the Cross Debugger,” 
later in this chapter. 

On the host machine, you need: 

□ the source code for your application. 

□ the executable file for your application. The executable file should 
have been compiled with one of the debug options. 


Using Cross-Debugging Mode 

Debugging a program in cross-debugging mode is a four-step process: 

1. Start the kernel (CPRK) on the target machine. 

2. Start the cross debugger (CPRX) on the host machine. 

3. Debug your program. 

4. Terminate the kernel and the cross debugger. 

The following sections describe each of these steps. 

Start the kernel on the target machine with the following Shell 
command: 

cprk [options] 

The only options CPRK accepts are the communications configuration 
options described in “Defining the Communications Parameters.” You 
cannot start the kernel from the Workbench. 

The kernel acts as a server, waiting for a request from the cross 
debugger to start a debugging session. The kernel displays its copyright 
information and diagnostic output in a Shell window. 

Note: If you are debugging over a serial port, you must start the 

kernel before starting the cross debugger. If you are using named 
pipes, the order does not matter. 

The cross debugger runs like CodeProbe, except that the program 
being debugged runs on another machine. Start the cross debugger on 
the host machine with the following Shell command: 


cprx [options] tar get-executable-filename [program-options] 



You cannot start the cross debugger from the Workbench. 

The target-executable-filename parameter is the name of the program 
to be debugged. By default, CPRX and CPRK look for the program in 
the current directory of both the host and the target machines. If you 
specify a pathname, CPRX and CPRK look in that location on both 
machines. If the executable file is located in different places on the 
target and host, then use the -symf ile option on the CPRX command 
to specify where the executable file resides on the host machine. CPRK 
still looks in the location specified by target-executable-filename. 

If you specify anything on the command line after the target- 
executable-filename, cprx passes these arguments to your program. 

CPRX supports any of the options available to the native debugger, 
CodeProbe. Chapter 1, “Getting Started,” describes CodeProbe’s 
options. The cross debugger also supports the options described in 
“Defining the Communications Parameters.” In addition, CPRX accepts 
the following options: 

-symf ile filename 

specifies the location of the executable file on the host machine. If 
the executable file is located in different places on the target and 
host, then use this option, to specify where the executable file 
resides on the host machine. CPRK still looks in the location 
specified by target-executable-filename. 

-x 

strips all debugging information from the host’s version of the 
executable file, copies the stripped version to the target machine, 
and tells CPRK to invoke the just-transmitted version. This option 
allows CPRK to run constantly without changing disks or rebooting 
(as long as your program does not crash). 

If the cross debugger does not open its windows after you enter the 
cprx command, communications have not been successfully 
established. You can terminate CPRX by entering Control-C in the Shell 
in which you enter the cprx command. Then, try to determine why 
the cprx command was not successful. 
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Both the cross debugger and the kernel accept the following command- 
line options: 

-pipe [name] 

specifies that a named pipe is to be used instead of the serial port. 
If name is not specified, pipe : cpr is used. CPRX or CPRK will 
open two pipes using name as a base, name_d and name— k. 

To communicate successfully over a network, you must invoke 
either cprx or CPRK with a pipe filename that refers to a pipe on 
the other machine. If your network allows you to refer to a pipe 
device on an attached machine by specifying 

net: pip e/pipename 

then you can start CPRK on the target machine using 
cprk -pipe net:pipe/cpr 

and start CPRX on the host machine with the -pipe option 
without a pipename. 

-device [name] 

specifies that the named device should be opened for 
communications if -pipe was not specified. The default is 
serial . device. 

-unit [number] 

specifies the unit number of the communications device if -pipe 
was not specified. The default is zero (0). 

-speed [number] 

specifies the baud rate of the communications device if -pipe was 
not specified. The default is the value is set with the Serial editor in 
the Prefs drawer from Workbench. 

Once started, the cross debugger behaves just like the normal 
debugger, except entering Control-C in the CPRX Dialog window 
does not always stop the program executing on the target machine. All 
interaction with the debugger occurs on the host machine through 
CPRX. All interaction with the program being debugged occurs on the 
target machine. 
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If possible, you should allow your program to run to completion before 
terminating the kernel or cross debugger. 

After you have finished debugging your program, you can terminate 
the kernel and the cross debugger in one of two ways: 

□ Terminate both CPRX and CPRK by entering the finish command 
in the CPRX Dialog window. The program being debugged is 
automatically terminated if it has not yet completed execution. 

□ Terminate only CPRX by entering the quit command. CPRK 
continues running, so you can start another CPRX session. The 
program being debugged is automatically terminated if it has not yet 
completed execution. 


Example: Using the Serial Port 

You want to start a cross-debugging session to debug a program named 
myprog using the serial port at 19200 baud. The program to be 
debugged resides in the current directory on the host machine, so you 
can use -x to copy it to the target machine. You would enter the 
following commands on the target and host machines: 

target machine 

cprk -speed 19200 
host machine 

cprx -x -speed 19200 myprog 

Example: Using Named Pipes 

You want to start a cross-debugging session to debug a program named 
myprg across a network using named pipes. The program to be 
debugged resides in temp : on the target machine and in work : on 
the host machine, You would enter the following commands on the 
target and host machines: 

target machine 

cprk -pipe pipename 
host machine 

cprx -pipe pipename -symfile workimyprg tmp:myprg 



105 


Command and Built-in 
Function Reference 

105 Introduction 

105 Summary of CodeProbe Commands 
106 Displaying Source 
106 Displaying Data 

106 Modifying Data 

107 Controlling Program Execution 

108 Debugging Multitasking Programs 
108 Customizing the Environment 
108 Quitting the Debugger 

108 Miscellaneous 
109 Command Reference 

195 Using CodeProbe’s Built-in Functions 

196 Summary of Built-in Functions 
196 Built-in Function Reference 


Introduction 

This chapter describes the CodeProbe commands and built-in functions 
provided with the SAS/C software. The commands and functions are 
described in alphabetical order. Commands are described first, 
followed by the built-in functions. 


Summary of CodeProbe Commands 

As described in Chapter 1, “Getting Started,” you can enter debugger 
commands in one of four ways: 

□ entering commands on the command line 

□ using pull-down menus 

□ using function keys 

□ using menu accelerator keys. 

This chapter describes the debugger commands as they are entered 
from the Dialog window. 

The following lists contain the names and descriptions all of the 
commands described in this chapter. These functions are grouped by 
task such as displaying source or modifying data. 
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Command 

Description 

l[ist] 

lists the lines in a source file 

sh[ow] 

sets the Source window to display specified source 

so[urce] 

displays the source file 

Command 

Description 

ar[gs] 

displays the arguments to a function 

c[all] 

evaluates an expression and discards the result 

dfisplay] 

displays the value of an expression 

du[mp] 

dumps memory contents 

dz[ero] 

displays memory as a null-terminated ASCII string 

ec[ho] 

displays a string 

f r[egister] 

displays or modifies floating-point registers 

hu[nks] 

lists the addresses and sizes of all hunks 

r[egister] 

displays or modifies registers 

rf [lag] 

displays or modifies flags 

symb[ol] 

finds the symbol nearest to the specified address 

unassemble] 

displays memory as assembler instructions 

w[atch] 

sets a watch on a variable or memory 

wb[reak] 

sets a watch break 

wc[lear] 

clears one or more watches 

wdfisable] 

disables one or more watches 

we[nable] 

enables one or more watches 

wha[tis] 

determines the type of an object 

wl[ist] 

lists all watches 

Command 

Description 

f r[egister] 

displays or modifies floating-point registers 

r[egister] 

displays or modifies registers 

se[t] 

modifies the values of variables or memory locations 
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Program 

Execution 

Command 

Description 

bc[lear] 

clears one or more breakpoints 


bd[isable] 

disables one or more breakpoints 


be[nable] 

enables one or more breakpoints 


bl[ist] 

lists all breakpoints 


b[reak] 

sets a breakpoint 


env 

sets the environment 


g[°] 

continues execution until a breakpoint is encountered 
or the program exits 


j[urap] 

changes the current execution point 


p[roceed] 

single-steps over function calls 


ps 

single-steps over function calls by source line 


res[tart] 

restarts the program being debugged 


ret[urn] 

returns immediately from the current function 


sta[rt] 

restarts the program being debugged 


t[race] 

single-steps into function calls 


ts 

single-steps by source line into function calls 


wb[reak] 

sets a watch break 


wc[lear] 

clears one or more watches 


wd[isable] 

disables one or more watches 


wefnable] 

enables one or more watches 


whe[re] 

shows the calling sequence 


wl[ist] 

lists all watches 
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Quitting the 
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Miscellaneous 


Command 

Description 

a[ctivate] 

activates a task under debugger control 

ca[tch] 

catches a task not currently under debugger control 

deactivate] 

deactivates a task under debugger control 

det[ach] 

detaches a task from debugger control 

sym[load] 

reads symbol information from an executable file 

ta[sks] 

displays system tasks 

Command 

Description 

al[ias] 

defines an alias for a debugger command 

def [ine] 

defines a macro 

ex[ecute] 

executes a debugger command file 

expand 

expands and displays a command line 

op[t] 

shows option values or changes the value of a 
debugger option 

unal[ias] 

deletes an alias 

und[ef ine] 

deletes a macro definition 

Command 

Description 

f in[ish] 

terminates the kernel and the cross debugger 

q[uit] 

terminates the debugger 

Command 

Description 

c[all] 

evaluates an expression and discards the result 

h[elp] 

displays help information 

i°[g] 

logs debugger commands to a file 

sea[rch] 

searches for a string in the current source file 

sle[ep] 

pauses for the time specified 

sym[load] 

reads symbol information from an executable file 

wi[ndow] 

opens or closes a window 

wl[ist] 

lists all watches 
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Command Reference 

This section describes each of the CodeProbe commands. The 
commands are listed in alphabetical order. Each command and 
function description includes the following sections (if applicable): 

Synopsis shows the format of the command. 

Description describes what the command does and contains all the 
information you need to use the command. 

Examples contains example commands showing how to use the 
command. 

See Also refers you to the descriptions of commands that contain 
related information. 
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Description 

Examples 


Activates a task under debugger control 
activate] [task-name | task-address] 

The activate command activates a task that was deactivated by the 
deactivate command. The task is activated when the next go, 
proceed, or trace command is executed. 

The task-name is the name of the task, and task-address is the 
address of the task as specified by the tasks command. You can 
specify only one of these parameters. 

activate "Child" 

activates the task named Child under debugger control, 
activate 0x7D9F884 

activates the task with a task block starting at address 0x7D9F884. 


See Also catch, deactivate, detach, tasks 
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alias 

Synopsis 

Description 


Examples 


See Also 


Defines an alias for a debugger command 
al[ias] [name [definition]] 

If you do not specify any arguments, the alias command displays the 
list of all currently defined aliases. If you specify a name as the only 
argument, alias displays the definition for that name. Any text 
following the name parameter is treated as a definition and is used to 
define the alias. 

For a complete description of aliases, see Chapter 2, “Customizing 
the Debugging Environment.” 

alias 

displays a list of all alias definitions, 
alias foo 

displays a definition of foo. 
alias next proceed 

defines next to be an alias for proceed, 
alias pr display foo, bar, $* 

defines pr to be an alias that executes the display command 
printing the value of foo, bar, and any variables entered after the 
pr. 

alias doit {go $1; d foo} 

defines doit to execute the go command using the first parameter, 
and displays the variable named foo. 
alias doit [go $ 1 ; \ 
d f oo } 

uses the backslash command to split a command across two lines. 

alias doit "go $1; d $2" 

uses positional parameters with multiple commands. The first 
parameter, $ 1 , is passed to the go command, and the second 
parameter, $2, is passed to the display command. 

alias this display * this 

defines this to display the object pointed to by the this pointer 
in C + + when CodeProbe is inside of a C + + member function. 
The C++ this pointer points to the object that invoked the 
member function. 

define, unalias, undefine 
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args Displays the arguments to a function 
Synopsis ar[gs] [/unction-name] 

Description The args command displays all of the argument names and values to 
the current function or the function specified by the function-name 
parameter. If you specify a function-name, the function must be in the 
calling sequence, as displayed by the where command. 

Examples args 

displays the arguments to the current function, 
args sort 

displays the arguments to the sort function, 
args chessBoard: rmovePiece 

displays the arguments to the C+ + member function 
chessBoard: imovePiece. 


See Also display, env, where 
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Synopsis 

Description 


Examples 


See Also 


Clears (deletes) one or more breakpoints 

bc[lear] integer [integer...] 

bc[lear] * | l[ast] 

be [ 1 e a r ] integer . . integer 

The bclear command clears (deletes) one or more breakpoints. When 
a breakpoint is cleared, it ceases to exist and can be reinstated only by 
issuing the break command again. To disable breakpoints 
temporarily, use the bdisable command. 

The integer parameter specifies the breakpoint number as displayed 
by the blist command. You can specify as many breakpoint numbers 
as needed. An asterisk clears all breakpoints, and last clears the 
most recently set breakpoint. You can specify a range of breakpoints 
with integer . . integer. 

bclear 256 

clears the breakpoints numbered 2, 5, and 6. 
bclear last 

clears the last breakpoint set. 
bclear * 

clears all breakpoints, 
bclear 4 . . 7 

clears breakpoints 4, 5, 6, and 7 
bclear 3 . . 4 last 9 

clears breakpoints 3 and 4, the last breakpoint that was set, and 
breakpoint 9. 

bdisable, benable, blist, break, welear 
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bdisable 

Synopsis 

Description 


Examples 


Disables (turns off) one or more breakpoints 

bd[isable] integer [integer . . .] 
bd[isable] * | l[ast] 
bd[isable] integer . . integer 

The bdisable command disables (turns off) one or more breakpoints. 
When a breakpoint is disabled, it is not recognized by CodeProbe, but 
it remains on the list of current breakpoints. To re-enable a disabled 
breakpoint, use the benable command. To remove the breakpoint 
from the list, use the be 1 ear command. 

The integer parameter specifies the breakpoint number as displayed 
by the blist command. You can specify as many breakpoint numbers 
as needed. An asterisk disables all breakpoints, and last disables the 
most recently set breakpoint. You can specify a range of breakpoints 
with integer, .integer. 

bdisable 256 

disables the breakpoints numbered 2, 5, and 6. 
bdisable last 

disables the last breakpoint set. 
bdisable * 

disables all breakpoints, 
bdisable 4 . . 7 

disables breakpoints 4, 5, 6, and 7. 
bd 3. .4 last 9 

disables breakpoints 3 and 4, the last breakpoint that was set, and 
breakpoint 9. 


See Also bclear, benable, blist, break, wdisable 
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benable 

Synopsis 

Description 


Examples 


See Also 


Enables (turns on) one or more breakpoints 

be[nable] integer [integer . . . ] 
be[nable] * | 1 [ast ] 
be[nable] integer, .integer 

The benable command enables (turns on) one or more breakpoints 
that have been disabled by the bdi sable command. 

The integer parameter specifies the breakpoint number as displayed 
by the blist command. You can specify as many breakpoint numbers 
as needed. An asterisk enables all breakpoints, and last enables the 
most recently set breakpoint. You can specify a range of breakpoints 
with integer . . integer. 

benable 256 

enables the breakpoints numbered 2, 5, and 6. 

benable last 

enables the last breakpoint set. 
benable * 

enables all breakpoints, 
benable 4 . . 7 

enables breakpoints 4, 5, 6, and 7. 
be 3 . . 4 last 9 

enables breakpoints 3 and 4, the last breakpoint that was set, and 
breakpoint 9. 

bclear, bdisable, blist, break, wenable 
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blist Lists all breakpoints 
Synopsis bl[ist] 

Description The blist command displays one or more breakpoints. The integer 
parameter specifies a breakpoint number. You specify one breakpoint 
or a range of breakpoints. If you specify last, then blist displays 
the last breakpoint set. If you specify an asterisk (*) or if you do not 
specify any parameters, blist displays the list of all breakpoints, as 
shown in the following example: 

1 Ox 1CA8 example :\example.c\main 38 (1 hit) 

after(3) when(i==4) 

2 Ox 1 E 1 4 example:\example.c\initarr 62 (1 hit) 

3* 0xlD70 example: \example.c\main 43 

4 0x1DA4 example :\example.c\main 45 
trace {echo Hi) 

The numbers 1, 2, 3, and 4 are breakpoint numbers. You can use 
these numbers to identify a specific breakpoint in the be 1 ear, 
bdisable, and benable commands. 

If the breakpoint number is followed by an asterisk (as in breakpoint 
number 3), the breakpoint is disabled and will not be triggered until 
you enable it with the benable command. Following the breakpoint 
number is the hexadecimal address at which the breakpoint resides. If 
the executable module contains sufficient debug information, the 
hexadecimal address is followed by the location that it represents. For 
example, breakpoint 1 resides at address 0xlCA8, which occurs at line 
38 of the main program. The hit count is the number of times that the 
breakpoint has been triggered. If any options (such as after or 
trace) are associated with the breakpoint, these commands are 
displayed on the line following the breakpoint number and address. 


See Also bclear, bdisable, benable, break, wlist 
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break 

Synopsis 

Description 


Sets a breakpoint 

b[reak] location [after {integer)] [when (expression)] [tr[ace]] 
[q[uiet]] [te[mp]] [{ cmd-list }] 

The break command sets a breakpoint at a location specified by the 
location parameter. You can use a dollar sign to specify the current 
location. 

If you specify a C + + overloaded function name as the location, the 
debugger displays a requester that allows you to select the function on 
which you want to set a breakpoint. You can click on the function 
name or use the arrow and Return keys to select a function. 

When you are setting a breakpoint on a C + 4- member function or 
operator member function, you must specify the class, followed by two 
colons, and then the member function or operator member function 
name. 

The break command supports the following options: 

after specifies the minimum number of times the specified 
line must be executed before the breakpoint is 
triggered. The integer you specify with the after 
option is called the pass count. Each time the 
breakpoint is hit, the pass count is tested. If the pass 
count is greater than 1, the pass count is decremented 
by 1, and execution continues. The breakpoint is 
triggered when the pass count equals 1. For example, 
if you specify a pass count of 5, the breakpoint is 
triggered when the line is executed the 5th time. For 
break commands that do not contain an after 
clause, the pass count is set to 1. The blist 
command shows the current pass count for each 
breakpoint. 

when specifies an expression that must evaluate to true 

(nonzero) before the breakpoint is triggered. You can 
specify the after and when options in any order. If 
you specify both options, the pass count is tested and 
decremented only if the when condition is true, 
trace continues execution automatically after the breakpoint 
is triggered, unless you reach the breakpoint by single- 
stepping. If you reach the breakpoint by single- 
stepping, then the trace option has no effect, 
quiet suppresses the default message showing the location 
when the breakpoint is triggered. 
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break 

( continued ) 


► Caution 


Examples 


Sets a breakpoint 


temp deletes the breakpoint after it has been triggered. 

{ cmd-list } specifies commands that you want the debugger to 

execute each time the breakpoint is triggered. You can 
use the backslash (\) to continue the command list 
onto more than one line. 

Note: To avoid confusion, the break command does not use the 
default radix setting. You must specify Ox for an address; otherwise, 
you will be specifying a line number. For example, even if the radix is 
set to hex, the following command specifies a break command for 
line 2 0 and not address 0x20: 

b 20 

A breakpoint is triggered when all of the following conditions are 
true: 

□ execution has reached the address shown 

□ the when and after conditions, if specified, are true, 

□ the breakpoint is enabled. 

Incorrect use of breakpoints may crash your machine. 

A breakpoint is implemented by placing an illegal instruction at the 
desired location. All tasks under the debugger’s control have a trap 
handler that reports back to the debugger when the illegal instruction 
is executed. If you must place a breakpoint in shared code, such as a 
resident library under test, be sure that any task that might open the 
library is under debugger control. Never place breakpoints in libraries 
that you do not control. A 

break $ 

sets a breakpoint at the current line. 

b 14 

sets a breakpoint at line 14 of the current module, 
b sort 

sets a breakpoint at the first line of the sort function, 
break sort return 

sets a breakpoint at the return from the sort function, 
break \myf ile . c:\sort 14 

sets a breakpoint at line 14 of sort in the module named 
myf ile . c. 
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break Sets a breakpoint 
(continued) 

break mylib. library :myfunc 

sets a breakpoint at the first line of the myf unc function in the 
shared library mylib . library, 
b $ after(5) 

breaks the fifth time the current line is executed, 
break 0x804A 

sets a breakpoint at the absolute address 0x8 0 4 A. 
break 14 when (i > 5) {di p L 16; b sort 26 
when (i == 8); bl ; go} 

sets a breakpoint on line 14 that performs the commands given 
inside the curly braces if i > 5 evaluates true. 

b 8 trace quiet {d "i = ", i} 

prints a message of the form " i = value " every time line 8 is 
executed. 

break 100 temp {d foo) 

stops at line 100, prints foo, and deletes this breakpoint. 

break myclass : :myf unc when(i == 5) 

sets a breakpoint on the member function myf unc in class 
myclass when i > 5 evaluates to true, 
break myclass :: operators- and break myclass: : + 

set a breakpoint on operator+ in myclass. Do not enter a space 
between the keyword operator and the operator itself. 

break myclass : imyclass 

sets a breakpoint on a constructor for myclass. 
break myclass : :'^myclass 

sets a breakpoint on a destructor for myclass. 

See Also bclear, bdisable, benable, blist, go 
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call Evaluates an expression and discards the result 
Synopsis c[all] expression 

Description The call command evaluates an expression and discards the result. 
This command is useful when you do not care about the value 
returned by an expression and is equivalent to the following statement 
in C language: 

expression ; 

The most common use of the call command is to call a function in 
your program, though function calls also may appear in arbitrary 
expressions in other commands. For example, you may want to write a 
function to display the contents of a complex structure and call that 
function at various points during the execution of your program. 

If you want to see the value returned by an expression, use the 
display command. 

The debugger looks at the types of the parameters specified and not 
at the definition of the function or any prototype. Thus, the debugger 
does not flag an error if the wrong number of parameters are 
specified, nor does it perform automatic casting of types or allow 
passing of char, short, or float types. For example, the following 
command passes two parameters, an int and a double, regardless of 
how the function is declared: 

call f ( 2 , 1.5) 

CodeProbe supports standard C syntax for function calls. Either a 
function name or an expression evaluating to a function type may be 
specified before the opening parenthesis. Thus, the call command can 
be used only to call functions or evaluate expressions that point to a 
function. For example, if pf is a function pointer, and f unc is a 
function, the following commands are allowed: 

call func( ) 
call (*pf)() 

However, the following commands are not allowed: 

call pf ( ) 
call Ox 1 34 ( ) 
call register () 
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call 

( continued ) 


Examples 


See Also 


Evaluates an expression and discards the result 


You cannot use the call command to execute a function after your 
program has ended. 

If a breakpoint is hit, a signal is caught, or the program terminates 
in the middle of a function call, the debugger aborts the expression 
and leaves you at that location. A warning is printed if any parameters 
are not cleaned off the stack. This may cause a return to an invalid 
location later if execution is allowed to continue. If this happens, you 
should enter the restart command. 

call status ( ) 

calls the status function, 
call print ( "Test" , 300) 

calls the print function passing in a string and an integer 
parameter. 

call (*fp) ( Sarr [5] , j+10, 3.0) 
evaluates arbitrary expressions. 

display, env, where 
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catch 

Synopsis 

Description 


Examples 
See Also 


Places a task under debugger control 
ca[tch] ["task-name" \ address ] 

The catch command places a task under the debugger’s control 
(catches a task). You can use this command to gain control of tasks that 
were not started under the debugger. For example, you may find that a 
process or task not started under the debugger is behaving in an 
unpredictable or undesired manner. The task may be caught in an 
infinite loop or waiting on some message port for a message that will 
never come. 

The task-name and address are the task and address as displayed by 
the tasks all command. 

If the task that you want to catch is a process, this command uses 
the process structure to find the code segments associated with the 
executable module. If you are running SegTracker and the task you 
catch was launched after SegTracker, just enter symload, and 
CodeProbe will automatically find the seglist. If you are not running 
SegTracker, you must locate the task’s seglist yourself and specify it on 
the symload command. 

For more information on segment lists, see The AmigaDOS Manual, 
3rd Edition. 

catch "Child" 

catches the task named Child, 
ca 0x7D9F8 8 4 

catches the task with a task block starting address 0x7D9F884. 
activate, deactivate, detach, symload, tasks 
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deactivate 

Synopsis 

Description 

Examples 


Deactivates a task under debugger control 
deactivate] [" task-name " | address ] 

Normally, the debugger starts all tasks under its control when you 
enter a go or proceed command. You can use the deactivate 
command to prevent a task from running, unless it is the current task. 
You can reactivate the task with the activate command. 

The task-name and address are the task name and address as 
displayed by the tasks command. 

dea "Child" 

deactivates the task named Child that is running under control of 
the debugger. 

deactivate 0x7D9F884 

deactivates the task with a task block starting at address 
0x7D9F8 8 4. 


See Also activate, catch, detach, tasks 
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define 

Synopsis 

Description 


Examples 


See Also 


Defines a macro 

[#]def[ine] name [definition] 

[# ]def [ine] name[parm [,parm...]) [ definition ] 

The define command provides a general macro substitution facility 
that is nearly identical to the mechanism provided by the C 
preprocessor. Macros defined in the debugger are expanded anywhere 
within a line of text except when 

□ the macro occurs inside quotes or filenames 

□ the macro is prefixed with a backtick character (' ). 

The # sign is optional and allows the debugger to read C header files 
(.h files) using the execute command. 

The define command does not support the ANSI C # and ## 
operators. 

define 

displays all the macro definitions, 
define foo 

defines foo as a null definition, 
def foo bar 

defines foo to be bar. 
define func(a,b) (a+b) 
defines func with parameters. 

alias, unalias, undefine 
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detach 

Synopsis 

Description 


Examples 
See Also 


Frees a task from debugger control 
det[ach] [" task-name " | address] 

The detach command frees a task from debugger control. 

You may want to allow one or more tasks spawned by a task under 
the debugger to run freely and not under the control of CodeProbe. 

For example, a task designed to respond to Intuition events may cause 
the system to lock up if it does not respond to menu events quickly. 
You may not want such a task to be stopped when other tasks hit a 
breakpoint. 

The task-name and address are the task name and address as 
displayed by the tasks command. 

To use the detach command, first set a breakpoint at the entry 
point to the task. CodeProbe will hit this breakpoint when the task is 
launched, which allows you to detach the task right away. When the 
breakpoint is reached, use the tasks command to identify the address 
or name of the task (you may know this based on your code). Then, 
clear all the breakpoints in the task, including the breakpoint that you 
set at the beginning of the task. The task will crash if it hits a 
breakpoint after it has been detached. After you clear all the 
breakpoints, enter the detach command with the task name or 
address. Also, do not detach a program if any of its child processes 
continue to run in the same code segment. 

The detached task is not removed automatically when you quit the 
debugger, and it can continue running even after you exit CodeProbe. 
Since CodeProbe frees all of the memory containing the code used by 
the detached task, the program will be executing in freed memory, and 
it may crash. Make sure that the program runs to completion before 
you quit the debugger. 

If you later want to re-attach the task to the debugger, you can use 
the catch command. 

detach "Child" 

detaches the task named Child from debugger control, 
det 0xC08540 

detaches the task with a task block starting at address 0xC08540. 
activate, catch, deactivate, tasks 
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display 

Synopsis 

Description 


Examples 


Displays the value of an expression 

d[isplay] expression [" format "][, expression ["format"]]... 
d[isplay] string[, string]... 

The display command evaluates the value of the expression 
parameter and displays the result. The expression parameter can be 
any C expression containing constants, variables, and function calls 
from the program being debugged. Any number of expressions and 
strings can be specified, separated by commas. All expressions are 
displayed on the same line. 

If you do not specify a format, the display command chooses the 
default format based on the type of the expression. Values of type 
char are displayed as characters as well as in decimal and 
hexadecimal format. If the character is unprintable, it is displayed as 
an escape sequence, for example, \n or \xAC. Values of type int and 
long are displayed in decimal and hexadecimal format, and floats 
and doubles are displayed in floating-point format. 

To override the default format, you can specify a printf format 
containing conversion operators after each expression. No error 
checking is done on the format parameter, so strange results are 
possible. The format may contain up to two conversion operators for 
short and long types but only one for all other types. Refer to the 
description of the printf function in the SAS/C Development System 
Library Reference for more information. 

All members of structures, unions, and arrays are displayed using 
the default formats. You can display partial arrays by specifying the 
first and last elements to display. For example, the following command 
displays array elements 3, 4, and 5: 

display a[3. .5] 

To display all elements in an array, use an asterisk (*). 

The string parameter can be any standard C string in double quotes 
as described in Chapter 1, “Getting Started.” 

To display a null-terminated string, use the dzero command. To 
dump an area of memory, use the dump command. 

display i 

displays the variable i. 
d a "a=%10.5e" 

displays a using a printf style format specifier. 
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display Displays the value of an expression 
(continued) 

d p->d [ 5 ] + f ( 3 ) 

displays the value of an expression containing a function call. 

display "X is", x, "J is", j 

displays the value of several arguments including strings. 

d x "X is %d" , j "J is %d" 

displays the value of several arguments using printf style format 
specifiers, 
d a [ 3 ] 

displays the value of an element of an array, 
display a [ 3 . . 5 ] 

displays the value of elements 3 through 5 in an array named a. 
d a [ * ] 

displays the value of every element of an array, 
d myobject 

displays the contents of the object myobject. 
d myobjectptr 

displays the address value of the object pointed to by the object 
pointer myobjectptr. 
d *myobjectptr 

displays the C+ + object pointed to by the object pointer 
myobjectptr. 

d myobject .mypublicmember 

displays the contents of the public member, mypublicmember, of 
the object myobject. 
d myobjectptr->mypublicmember 

displays the contents of the public member of the object pointed to 
by the object pointer. 


See Also call, dump, dzero 
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dump Dumps memory contents 

Synopsis du[mp] [variable \ address \ range] [$] [ format[itemsize ] | text] 

Description The dump command displays an area of memory. If you do not specify 
any parameters, the dump command uses the same parameters that 
you specified in the previous dump command (if any), but it displays 
memory beginning where the previous dump command ended. The 
variable, address, range, array-slice or $ parameter specifies the 
memory to be displayed. If you use the 1 or L form of the range, the 
range length is scaled by the itemsize. The $ specifies the memory 
immediately following the last memory dumped when the format or 
text parameters are used. The $ is ignored if a variable, address, or 
range parameter has already been specified making it useful for abases 
where the dump address may be omitted. 

The format parameter controls the format of the dump and its value 
can be any of the following: 


a[scii] FFPffloat] IEEEffloat] 

bfinary] ffloat] ofctal] 

dfecimal] h[ex] ufnsigned] 

The default format is hex. 

If you specify a format parameter, you also can specify an itemsize 
parameter to control the length of each item dumped. The itemsize 
parameter can have a value of 1, 2, 4, or 8. The itemsize parameter is 
concatenated onto the end of the format parameter (for example, b4 
for a binary format of length 4). If you do not specify itemsize, 
CodeProbe uses a default. As shown in the following table, the 
allowable size and default values depend on the format specified. 


Format 

Default 

Allowed Sizes 

ascii 

1 

1 

binary 

1 

1, 2, 4 

decimal 

4 

1, 2, 4 

FFPf loat 

4 

4 

float 

8 

4, 8 

(continued) 
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dump 

(continued) 

Dumps memory contents 



Format 

Default 

Allowed Sizes 


hex 

4 

1, 2, 4 


IEEEf loat 

8 

4, 8 


octal 

4 

1, 2, 4 


unsigned 

4 

1, 2, 4 


The text parameter is used to specify that an ASCII representation 
of the memory dump should be displayed. 

Aliases For The To provide compatibility with previous releases, CodeProbe supports 
dump Command the following aliases for the dump command: 

da 

dumps a range of memory as ASCII characters, 
db 

dumps a range of memory in both hexadecimal and ASCII format, 
dc 

dumps a range of memory in decimal format, 
dd 

dumps a range of memory as 8-byte floating-point numbers in IEEE 
format, 
df 

dumps a range of memory as 4-byte floating-point numbers in IEEE 
format, 
df f p 

dumps a range of memory as 4-byte floating-point numbers in FFP 
format, 
di or dl 

dumps a range of memory in integer format using decimal 
representations of the integers, 
dw 

dumps a range of memory in short integer (16-bit) format using 
hexadecimal representations of the integers, 
dp 


dumps a range of memory in 4-byte hexadecimal format. 
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dump 

(continued) 


Examples 


See Also 


Dumps memory contents 


ds 

dumps a range of memory in short integer (16-bit) format, using 
decimal representations of the integers. 

dump var 

dumps memory contents of variable var. 
du var L 13 hexl 

dumps memory contents for 13 bytes using 1-byte hexadecimal 
format. 

du varl . . var2 ascii 

dumps memory contents between varl . .var2 in ASCII format, 
dump 0xAF8 100 L 8 

dumps memory contents for 8 longs (32 bytes) starting at absolute 
address 0xAF8 100. 

display, dzero 
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dzero 

Synopsis 

Description 


Examples 


See Also 


Displays memory as a null-terminated ASCII string 
dz[ero] variable \ address | array-slice 

The dzero command displays the contents of memory at the specified 
location as a null-terminated (\0) string. The location can be any of the 
following: 

nonpointer variable 

displays the memory contents starting at the address of the variable 
and continuing until the null character is found, 
pointer variable 

displays bytes starting at that address until a null character is 
encountered, 
absolute address 

displays the contents of that address until a null character is 
encountered. 
array-slice 

displays all of the strings pointed to by the elements in the slice of 
the array of char * elements. 

The dzero command wraps long strings on successive lines. You can 
use the opt strlen command to limit the number of characters 
printed in long strings. You can use the opt badchars command to 
control printing of strings containing unprintable characters. 

dzero string 

displays characters until the null character is reached, 
dz ptr 

displays data pointed to by ptr as a string, 
dz ptr [3 . . 7 ] 

displays each element in the array slice ptr [ 3 . . 7 ] until the 
null character is reached. 

display, dump 
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echo 

Synopsis 

Description 

Example 
See Also 


Displays a string 
ec[ho] [text] 

The echo command writes the specified text in the Dialog window. If 
the text contains semicolons, the semicolons must be preceded with a 
backslash (\ ;). The echo command does not expand defines or 
aliases. 

This command is useful for documenting the actions being taken in a 
debugger command file, the cprinit file, or AREXX macros. 

echo Starting programs; loading defines. 

displays the message following the echo command in the Display 
window. 

display, execute 
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env Sets the environment 
Synopsis env [function \ level ] 

env [-c[aller] | -subroutine] | -u[p] | -d[own] | -integer \ unteger ] 

Description The env command changes the environment for subsequent debugger 
commands. The environment is the state of the machine at a specific 
point in the calling sequence (that is, the position in the call chain and 
the contents of variables). Setting the environment to a previous point 
in the calling sequence, such as the point where the current function 
was called, returns the machine to the state it was in at that time. 
However, only the information that can be retrieved from the stack or 
procedure save areas will have been restored. Scratch registers and 
other components, such as the values of ex ter ns, that are not saved 
and restored by function calls remain relative to the current execution 
point in the program and are not changed. Nonscratch registers are set 
to the values for the new environment. 

The environment can be set to an absolute or relative position in the 
call chain. To set the environment to an absolute position, specify a 
function or level: 

function 

specifies the name of a function in the call chain. If the same 
function appears more than once in the call chain, the most deeply 
recursive one is selected. 
level 

moves the environment to the level specified, level must be an 
integer. Level 1 is defined to be the function in which you are 
currently stopped. The caller’s level is 2, its caller is level 3, and so 
on. These level number designations change as the program steps 
into and returns from functions. You can display level numbers 
using the where command or Calls window. 

The other forms to the env command set the environment relative to 
the current function: 

-caller, -up, and -1 

move the environment up one level to the caller of the current 
function. 

-subroutine, -down, and +1 

move the environment down one level toward the bottom of the call 
chain. 

+ integer 

moves the environment down the call chain the number of levels 
you specify. 
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env Sets the environment 
(continued) 

-integer 

moves the environment up the call chain the number of levels you 
specify. 

If you attempt to move the environment up or down more levels than 
there are in the call chain, a warning is displayed and the environment 
is moved as far as possible. 

Any command that causes the program to resume execution, such as 
the go or trace commands, automatically resets the environment to 
the last point of execution. Issuing the env command is the same as 
double-clicking on a function call entry in the Calls wdndow. 

Examples env 

sets the user environment to the last point of execution, 
env main; d i 

sets the user environment to main and display i. 
env -subroutine 

sets the environment to the called function (down 1 level), 
env -caller 

sets the environment to the caller function (up 1 level), 
env +5 

moves the environment down 5 levels, 
env 7 

moves the environment to the level 7. 
env myclass : :mymember function 

sets the environment to the called member function 
myclass: :mymemberf unction. 

See Also where 
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execute Executes a debugger command file 
Synopsis ex[ecute] filename 

Description The execute command reads and executes CodeProbe commands 
from the file specified by filename. If the file cannot be found, 
CodeProbe appends a . cpr extension to the filename and tries again. 
Thus, you can place a set of debugger commands in a file with a .cpr 
extension and specify the root filename, minus the extension, in the 
execute command. CodeProbe searches for the specified file in your 
normal Shell path as defined with the AmigaDOS path command: 

For example, you may have a file, cmds .cpr, that contains the 
following commands: 

break sort 
blist 
trace 
trace 

The execute cmds .cpr command produces output similar to the 
following: 

executing commands from cmds. cpr 
1 0xC32D3E sort:\sort.c\sort 22 
sort:\sort.c\init 5 
sort:\sort.c\init 9 

The debugger commands themselves are not displayed unless echo 
mode is turned on. 

If you are debugging a program frequently and want to set a number 
of breakpoints at the same places, you can place all of your breakpoint 
commands in a file and then use the execute command on this file. 
Using the execute command means that you do not have to re-enter 
the same commands each time you use the debugger. 

If the execute command is used in a command list, it must be the 
last command in the list. 

In the Dialog window, in line mode, and in execute files, lines 
containing only comments are ignored. In the Dialog window and in 
line mode, blank lines are treated as a proceed command. 
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execute Executes a debugger command file 
( continued ) 

Examples execute setvars 

executes the file named setvars or setvars . cpr. 
execute test/cmds . cpr 

executes the file named cmds .cpr located in the test directory. 
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expand 

Synopsis 

Description 

Examples 


See Also 


Expands and displays a command line 
expand [alias] command-line 

The expand command displays its arguments with all macros 
expanded. If you specify the alias option, this command also 
expands aliases. The command-line specifies any valid command-line 
entry that includes aliases or macros. 

expand alias dp 

expands the alias named dp to display the following: 
dump $ hex 4 

expand ISEQUAL(1,5) 

expands the macro IS EQUAL using the arguments 1 and 5. For 
example, if IS EQUAL has been defined as ( a == b ) , then it 
would be expanded to ( 1 = = 5 ) . 

alias, define 
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finish 

Synopsis 

Description 


Example 
See Also 


Terminates the kernel and the cross-debugger 
f in[ish] 

In cross-debugging mode, the finish command terminates the 
session. You should enter the finish command on the host machine. 
The host machine is the machine that displays the CodeProbe user 
interface. 

The cross debugger (CPRX) on the host machine tells the kernel 
(CPRK) on the target machine to terminate after cleaning up and 
closing the communications link. If you are not in cross-debugging 
mode, the finish command does not work. 

For a complete description of the cross debugger, see Chapter 8, 
“Using the Cross Debugger.” 

finish 

tells the kernel to terminate after disconnecting from the cross 
debugger. 

quit 
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fregister 

Synopsis 

Description 


Examples 


See Also 


Displays or modifies floating-point registers 
fr[egister] [register[ [ = Expression ] ] 

On machines that have a math coprocessor chip, the fregister 
command displays or modifies the contents of the floating-point 
registers. If you do not specify any parameters, the fregister 
command displays the current contents of all the machine’s floating- 
point registers in hexadecimal and as floating-point numbers. If you 
specify only a register name, the contents of the register are displayed. 
If you also specify an expression, then that expression is saved in the 
register. 

You can also use the display and set commands to display and 
modify the registers, and you can use the Register window to display 
the registers. 

f r 

displays all floating-point registers and flags, 
fregister fpO 30.14 

sets floating-point register f p 0 to 30. 14. 
fr fp2 = sales 

sets floating-point register fp2 equal to the value of sales, 
fregister fpl 

displays the value of floating-point register fpl. 
display, register, rflag, set 
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go Continues execution until a breakpoint is encountered or the program 
exits 

Synopsis g[o] [location [after (integer)] [when [expression)]] 

Description The go command begins execution of the program at the current 
location, which is identified by the address stored in the program 
counter (PC) register. Execution continues until a breakpoint is reached 
or until the program terminates, either normally or with an error. The 
location parameter specifies a location for a temporary breakpoint. If 
you specify a location, the temporary breakpoint exists only for the 
duration of the go command. The next time program execution stops, 
the breakpoint is cleared, even if the temporary breakpoint was not 
reached. The go command supports the following options: 

after 

specifies the minimum number of times the specified location must 
be executed before the breakpoint is triggered. The integer you 
specify with the after option is called the pass count. Each time 
the breakpoint is hit, the pass count is tested. If the pass count is 
greater than 1, the pass count is decremented by 1, and execution 
continues. The breakpoint is triggered when the pass count equals 
1. For example, if you specify a pass count of 5, the breakpoint is 
triggered when the location is executed the 5th time. For go 
commands that do not contain an after clause, the pass count is 
set to 1. The blist command shows the current pass count for 
each breakpoint, 
when 

specifies an expression that must evaluate to true (nonzero) before 
the breakpoint is triggered. 

You can specify the after and when options in any order. If you 
specify both options, the pass count is tested and decremented only if 
the when condition is true. 

Note: To avoid confusion, the go command does not use the 
default radix setting. You must specify Ox for an address; otherwise, 
you will be specifying a line number. For example, even if the radix is 
set to hex, the following command specifies a go command for line 20 
and not address 0x20: 

g 20 
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go Continues execution until a breakpoint is encountered or the program 
(continued) exits 

Examples go 

continues program execution to the next breakpoint or the end of 
the program, 
go 1 4 

continues program execution to line 14 of the current module. Line 
numbers are relative to a module and not a function. This example 
assumes that code was generated at line 14. You cannot use the go 
command to go to a line with no code generated, 
go sort 

continues program execution to the first line of the sort function, 
go \myf ile . c\sort 14 

continues program execution to line 14 of the sort function in 
module myf ile . c. This example also assumes that code was 
generated at line 14. 
go mylib . library :myfunc 

continues program execution to the myf unc function in the shared 
C library mylib . library, 
go $ after(5) 

continues program execution until the fifth time the current line is 
executed, 
go 0x804A 

continues program execution until absolute address 0x8 0 4A is 
reached. 

go myclass : :mymemberf unction 

continues program execution to the first line of the 
myclass: :mymember function function, 
go \myf ile . cxx\myclass : imymember function 14 
continues program execution to line 14 of the 
myclass : :mymember function function in module myf ile . 
cxx. This example assumes that code was generated at line 14. 
go mycxxlib . library : myclass : smymember function 
continues program execution to the 

myclass: imymember function function in the shared C+ + 
library mycxxlib . library. 


See Also break, proceed, ps, trace, ts 
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help Displays help information 

Synopsis h[elp] [command-or-topic] 
? [command-or-topic] 


Description The help command displays information about commands and 

operands. To display help about a specific command or topic, enter the 
command or topic as a parameter to the help command. 

In window mode, if you do not specify a command or topic, 
CodeProbe opens the Help window and displays a list of commands 
and topics. You can click on a command or topic to display more 
detailed information. In line mode, CodeProbe displays this same list of 
commands and topics, and you must enter help followed by the 
command or topic to see additional information. 

Each help screen contains a See Also section listing related 
commands and topics. To display information about one of these items, 
click on the command or topic. For example, the See Also section for 
the dump command fists the display and dzero commands. You 
can display the help screen for either of these commands by clicking 
on the name of the command. 

The Help window is an AmigaDOS window invoked on the 
AmigaGuide database sc : help/cpr . guide. 

Examples help 

displays a list of commands and topics, 
h break 

displays information about the break command. 

? break 

displays information about the break command. 
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hunks 

Synopsis 

Description 


Example 


Lists the addresses and sizes of all hunks 
hu[nks] 

The hunks command displays the list of loaded hunks, their 
addresses, and their sizes for the current executable file. 

The hunks command displays information in the following format: 

Hunk Address Size 

0 00C32AE8 0xB54 (2900) 

1 00C28570 0x27C (636) 

The size is displayed first in hexadecimal format followed by decimal 
format in parentheses. 

hunks 

lists all hunks for the current executable file. 
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jump 

Synopsis 

Description 


► Caution 


Examples 
See Also 


Changes the current execution point 
j[ump] location 

The j ump command updates the program counter to point to a new 
location. If you use the j ump command, the code between the previous 
execution point and the new location is not executed. The j ump 
command also allows you to re-execute code that you want to inspect 
more closely. 

For the location parameter, you can specify any value that would 
also be valid for the break or go commands. 

Note: The j ump command does not restore any program variables 
or memory locations. If you use j ump to re-execute a statement that 
increments a variable, the variable is incremented again when you step 
over that statement. 

Certain registers may not be set up the way the code that is jumped 
to expects. 

Using the j ump command is more likely to be safe if you always jump 
from one C source file line to another in the same function (not from 
assembly lines), and you have compiled with a debugging option that 
flushes non-register variables being held in registers to memory at C 
source line boundaries (that is, symbolf lush or fullf lush). If the 
jump command is used on optimized code, the registers are probably 
not set correctly. A 

Note: To avoid confusion, the jump command does not use the 
default radix setting. You must specify Ox for an address; otherwise, 
you will be specifying a line number. For example, even if the radix is 
set to hex, the following command specifies a jump command for line 
20 and not address 0x20: 

j 20 

j ump 1 2 

jumps to line 12 in the current function, 
jump 0x8 04E 

jumps to the address 0x8 0 4 E. 
env, go, return 
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list 

Synopsis 


Description 


Examples 


Lists the lines in a source file 

l[ist] 
l[ist] $ 

l[ist] +integer | - integer [L length] 
l[ist] line-range 

1 [1 s t] [executable-name :]\module [line-range] 

l[ist] [[executable-name :]\module\]function [line-range] 

In line mode, the list command lists the lines in a source file. 

If you do not specify any arguments, the list command displays 
lines starting with the current list line, and the number of lines that 
are displayed is controlled by the opt list command. The current 
list line is the source line at which the program is stopped. 

If you specify list $, the list command displays a number of lines 
above and below the current list line, and the number of lines above 
and below is controlled by the opt context command. 

See the description of the location parameter in Chapter 1, “Getting 
Started,” for a description of the executable-name, module, and function 
parameters. 

Note: Specifying the module is not supported with C+ + programs. 
If you specify a line-range, the line command displays the lines in 
that range. Specify the range using one of the following forms: 

starting-line [[ . . ]ending-line] 
starting-line L number-of-lines 

If you specify a module or function, CodeProbe opens the source file 
for that environment, if possible, and displays the desired line range. If 
you do not specify a line range or function, the listing begins at line 1. 
If you specify a function but do not specify a line range, CodeProbe 
lists lines beginning with the function declaration. 

Each time you enter the list command, the current list line is set 
to the line immediately following the last line listed, the current list 
line is also updated each time the program is allowed to execute. 

list 

lists the next group of lines. The number of lines listed is set by the 
opt list command, 
list $ 

lists lines around the fine pointed to by the current program 
counter. 
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list Lists the lines in a source file 
( continued ) 

list module 

lists first lines of the specified module, 
list \module 20 40 

lists lines 20 through 40 of the specified module, 
list \module 20 1 10 

lists 10 lines of the specified module starting at line 20. 
list +20 

starts listing lines 20 lines down from the current line, 
list -20 

starts listing lines 20 lines up from the current line, 
list -20 L 10 

lists 10 lines, starting 20 lines up from the current line, 
list foo 

starts listing at the declaration of the function named foo. 
list foo 10 20 

lists lines 10 through 20 of the function named foo. 

See Also opt, source, unassemble 
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listsym Lists all currently defined symbols 
Synopsis listsym [ symbol-name ] 

Description The listsym command displays the list of all symbols and as much 
information as possible about the symbol, such as current value, 
prototype, the address of the symbol (for externs), and mangled 
name. 


Examples listsym 

displays all of the currently defined symbols, 
listsym i 

lists the value of variable i. 
listsym myclass: :memfunc 

displays the prototype, address, and mangled name for memf unc in 
class myclass. 


See Also display 
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log 

Synopsis 

Description 


Examples 


Logs debugger commands to a file 
lo[g] [ log-command ] 

The log command saves, in a log file, a record of all activity in the 
Dialog window including commands and results. The name of the log 
file is set with the log file command. The default filename is 
cpr . log. 

The log command does not save menu selections. 

If you do not specify a log-command, the log command displays the 
current log state (either on or off) and the filename of the log file. 
The log-command parameter can be any of the following: 

append 

appends log information to the end of the log file, 
file filename 

specifies the filename of the log file and opens the file, 
off 

closes the log file, 
on 

opens a new log file, 
snap 

snapshots the contents of the Dialog window to the log file. 

If you enter a command that turns on the logging of your session, such 
as log on, log append, or log snap, but logging is already 
turned on, the log command itself is added to the current log file. If 
you change the log filename while logging is enabled, CodeProbe closes 
the current log file and opens a new one. The log file is automatically 
closed when you exit the debugger. 

log snap 

saves the dialog for the current session into the log file named 
cpr . log. 

log file foo.log 

sets the log file to the filename foo.log. 
log on 

enables the log file. 
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1 09 Logs debugger commands to a file 
(continued) 


log off 

disables the log file. 


log append 

enables the log file and appends new log information to the end of 
the log file. 
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modules 

Synopsis 

Description 


Examples 


See Also 


Lists all of the modules in an executable 
m[odules] [ location ] 

The modules command produces a list of all of the modules in an 
executable. If you do not specify a location, the debugger lists all of the 
modules for the current executable. If you specify a location, 

CodeProbe lists all of the modules for the specified executable. 

This command is not supported for C+ + programs. 

Note: This command accepts a location containing just an 
executable name, even though that is not legal for locations in general. 

mod 

lists all modules in the current executable, 
mod img: 

lists all modules in the executable img. 
mod img : \mod . c\f nc 

lists all modules in img. The mod. c and fnc are ignored, 
functions, variables 
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Opt Displays or changes the value of a debugger option 

Synopsis op[t] 

op[t] au[toswap] [on | off] 

op[t] ar[rdim] integer 

op[t ] bfadchar] integer 

op[t] ca[se] [on | off] 

op[t] cat[ch] [on | off] 

op[t] co[ntext] integer 

op[t] dev[ices] [on | off] 

op[t] e[cho] [on | off] 

op[t] ib[ytes] [on | off] 

op[t] ig[norepath] [on | off] 

op[t] 1 [i st ] integer 

op[t] rad[ix] [d[ecimal] | h[ex]] 

op[t ] ran[gelen] integer 

op[t] re[slib] [on | off] 

op[t] se[arch] [+ | -] directory[ , directory]... 

op[t] so[urce] c | a[sra] | m[ixed] | n[ext] 

op[t ] st[rlen] integer 

op[t] tab n 

op[t] t [ask] [task-name | task-address] 
op[t] u[nassemble] integer 

Description The opt command is used to display and change the current setting of 
the debugger’s options. The opt command by itself shows the current 
settings of all options, plus the current task. If you also specify an 
option and a setting, this command changes the debugger’s options as 
you specify. The following list describes the options and their possible 
values: 

arrdim 

specifies the maximum number of array elements that are displayed 
at one time with the display command. The default value is 20. 
If an array has fewer than the specified number of elements, all of 
the array’s elements are displayed. For larger arrays, the specified 
number of elements are displayed, followed by an ellipsis (...)• 
autoswap 

if set to on, pushes the program’s screen to the front each time 
control is given to your program. When a breakpoint is reached, 
the debugger screen is again pushed to the front. If you are single 
stepping through source code, the switching of screens will 
probably appear as a brief flash. Autoswap mode is particularly 
useful when debugging programs that require input from the 
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opt Displays or changes the value of a debugger option 
(continued) 


keyboard. The program’s screen is automatically pushed to the front 
whenever input is required. 

If set to off, the program’s screen is not pushed to the front. 

The default setting is off. 
badchar 

controls the number of non-printable characters that a dzero or 
display command will accept when displaying a string referenced 
by a character pointer. The default value is 3. A value of zero (0) 
indicates no limit, 
case 

controls case sensitivity for the search command. If you specify 
opt case on, the search command performs case-sensitive 
string searches. The default setting is off. 
catch 

if set to on, catches any new task generated by a task that is 
already under debugger control. The default setting is off. 

Note: Tasks started by a call to OpenDevice are controlled by 
the opt devices command, 
context 

controls the number of lines (context lines ) displayed above and 
below the current line. The default number is 2. In windowing 
mode, the maximum number of lines is limited by the number of 
lines in the Source window. In source mixed mode, it is not 
always possible to keep the correct number of lines above or below 
the current line. In line mode, this option controls the number of 
lines displayed with the list $ command, 
devices 

if set to on, the debugger attaches to, or catches, any new device 
process or task generated by a task under debugger control. When a 
device is opened for the first time, a new task may be created. The 
default setting is off. 
echo 

if set to on, tells the debugger to echo all commands to the Dialog 
window before executing them. This option is especially useful if 
you want to use the execute command to execute a file of 
debugger commands and see the commands and their output as 
they are executed. The debugger also displays commands that are 
invoked by selecting menu options or by double-clicking with the 
mouse. The default is off. 
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opt Displays or changes the value of a debugger option 
(continued) 


ibytes 

if set to on, tells the debugger to display the instruction bytes being 
disassembled. This affects the output of the unassemble 
command, and in windowing mode, it also affects the Source 
window in mixed and asm source modes. If this option is set to 
on, the second field of the disassembly contains a hexadecimal 
dump of the instruction. For example, if ibytes is set to on, the 
unassemble command may produce: 

0025F950 48E70130 MOVEM.L D7/A2-A3,-(A7) 

If ibytes is set of off, the same command would produce: 

0025F950 MOVEM.L D7/A2-A3 , -( A7 ) 

The default setting is off. 

For more information, see the description of the unassemble 
command, 
ignorepath 

if set to on, tells the debugger to ignore the pathname for the 
source file provided by the compiler. In this case, CodeProbe looks 
in the current directory for the source file. By default, 
ignorepath is set to off, and CodeProbe uses the entire 
pathname when searching for the source file. You can use this 
option and the opt search command to override the source 
filename specified in the object file. For more information, see 
Chapter 2, “Customizing the Debugging Environment.” 
list 

controls the default number of lines displayed by the list 
command in line mode. The default number is 6. 
radix 

sets the default input type for constants. You can specify 
hexadecimal or decimal. The default setting is decimal. If you 
specify hexadecimal, then you do not have to type the Ox before 
hexadecimal constants, 
rangelen 

controls the default size of ranges when no range size information 
is available. The default value is 64. This value is used when you 
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Opt Displays or changes the value of a debugger option 
( continued ) 


specify only an address parameter for the display, dump, or 
watch commands, 
reslib 

steps into resident libraries while tracing or running a program 
with watch breaks. The default setting is on. Leave this option on 
unless you want to debug your own resident libraries. However, 
tracing into system libraries such as Exec or Intuition can 
cause problems. Stepping into system libraries means that you are 
in ROM. You will not have C source code available, and you cannot 
set breakpoints in ROM. The debugger will not be able to figure out 
where you are. Also, you should disable all watch breaks before 
stepping into a ROM-resident library routine, 
search 

defines a set of directories that you want the debugger to search for 
the source code. For a complete description of the opt search 
command, see Chapter 2, “Customizing the Debugging 
Environment.” 
source 

controls how your source code is displayed in the Source window in 
windowing mode. You can choose one of three possible settings: 

C displays C or C++ source lines when you enter a 
trace or proceed command or when a breakpoint is 
triggered. In C mode, you cannot single step by 
assembly instruction. The default setting is C. 
asm displays disassembled code. The trace and proceed 
commands step by assembly instruction, 
mixed displays both assembly instructions and C or C+ + 
source lines. 

Repeatedly choosing the next value cycles through the three 
possible modes, 
str len 

controls the maximum number of bytes that are displayed when a 
character string is displayed with the display and dzero 
commands. The default number is 128. If the character string 
contains unprintable characters, fewer characters may be displayed, 
tab n 

sets tab stops every n columns in the Source window. The number 
n must be greater than zero. The default setting is 8. 
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opt Displays or changes the value of a debugger option 
( continued ) 

task 

displays the current task or, if you specify a task-name or 
task-address, changes the current task to the task you specify. The 
task-name and task-address are the task name and address of the 
task control block, as displayed by the tasks command. 

If you specify the name, the name should be unique. If the name 
is not unique, the debugger uses the first task with that name that 
appears in its task list. If the name contains a blank, enclose the 
name in double quotes. The task names are case sensitive. 

If you specify the task address, enter the address in hexadecimal 
notation (with a Ox prefix). 

When you change to a new task, CodeProbe displays a new set of 
registers. The highlighting of changed registers in the Register 
window may be incorrect since the debugger keeps track of changes 
only while stepping through a single task. The module displayed in 
the Source window may change. If the task was in a system or 
linked library, assembler lines are displayed. 

You may be able to display the calling sequence of the task by 
using the where command, but since assembler routines, including 
the Amiga system’s resident libraries, do not follow C language 
calling conventions, the information displayed by the where 
command may not be accurate. 

You can modify any registers, condition control register (CCR) 
flags, or stack variables, just as in the breakpointed task. You can 
also single step through the code. 

► Caution Incorrect use of breakpoints may crash your machine. 

A breakpoint is implemented by placing an illegal instruction at the 
desired location. All tasks under the debugger’s control have a trap 
handler that reports back to the debugger when the illegal 
instruction is executed. If you must place a breakpoint in shared 
code, such as a resident library under test, be sure that any task 
that might open the library is under debugger control. Never place 
breakpoints in libraries that you do not control. A 

unassemble 

controls the default number of instructions that are disassembled by 
the unassemble command in line mode when the source file is 
not available. When the source file is available, the unassemble 
command displays the disassembly for a single source line. This 
option has no effect in C mode or windowing mode. The default 
setting is 4. 
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Opt Displays or changes the value of a debugger option 
(continued) 

Examples opt 

displays the settings of all options, plus the current task. You 
cannot change the current task with the opt command, but you can 
use the j ump command to change the execution point, 
opt unassemble 10 

sets unassemble count to 10. 
opt search /src,/test 
sets search directories, 
opt search +test2 

appends a new search directory, 
opt task "Child" 

changes the current task to the task named Child, 
opt task 0x7D9F8 8 4 

changes the current task to the task with the address 0x7D9F884. 
opt task "Child of multi" 

changes the current task to the task named "Child of multi". 


See Also display, dzero, jump, list, unassemble 
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proceed 

Synopsis 

Description 


Examples 
See Also 


Single-steps over function calls 
p[roceed] [ integer ] 

In C mode, the proceed command steps over the number of source 
statements specified by the integer parameter. In Mixed or Asm 
modes, it steps over integer number of machine instructions. If 
CodeProbe encounters a function call, the function is executed as if it 
were a single statement. If you do not specify an integer, it defaults 
to 1. 

When you are debugging a C+ + program in C source mode, the 
proceed command steps over the translated C statements. In other 
words, if one C+ + statement was translated into more than two C 
statements, it will require two proceed commands to step over the 
C++ statement. 

If you press Enter at the CodeProbe prompt without typing any 
commands on the command line, CodeProbe executes a proceed 1 
command. You can also press the F6 key to enter the proceed 
command. 

proceed 

steps 1 source statement in C mode or 1 machine instruction if in 
Mixed or Asm modes, 
proceed 5 

steps 5 source statements in C mode or 5 machine instructions if in 
Mixed or Asm modes. 

go, ps, trace, ts 
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PS 

Synopsis 

Description 

Example 
See Also 


Single-steps over function calls by source line 
ps [ integer ] 

The ps command steps over the number of C source statements 
specified by the integer, even if mode is set to Mixed or Asm. If 
CodeProbe encounters a function call, the function is executed as if it 
were a single statement. If you do not specify an integer, it defaults 
to 1. 

When you are debugging a C + + program in C source mode, the ps 
command steps over the translated C statements. In other words, if 
one C+ + statement was translated into more than two C statements, 
it will require two ps commands to step over the C+ + statement. 

ps 2 

steps through two source lines regardless of the debugger mode, 
go, proceed, trace, ts 
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quit 

Synopsis 

Description 


Example 


Terminates the debugger 
q[uit] [-abort] 

The quit command terminates the debugging session and returns to 
the operating system prompt. 

In cross-debugging mode, the quit command terminates only the 
cross debugger (CPRX) on the host machine, leaving the kernel (CPRK) 
waiting for a new debug session. 

Normally, CodeProbe forces the program being debugged to call the 
exit function before the debugger terminates the program. The 
debugger then exits. If you invoke the debugger with the -startup 
option, the debugger exits without forcing the program to call exit. If 
you start CodeProbe with the -startup option, terminate CodeProbe 
on the target machine with the finish command instead of entering 
quit. 

If you specify the -abort option, the debugger will not call exit 
before terminating. If you think that your destructors, autotermination 
functions, or at ex it functions may cause system problems, then 
specify the -abort option. For example, if you determine during your 
debugging session that the memory heap managed by mall oc is 
corrupt, then you do not want to free that memory as CodeProbe exits. 
Normally, this memory is freed by an autotermination function called 
from exit. 

If you specify -abort, then cleanup for your program is not 
performed. Files opened with fopen or open are not closed, memory 
allocated with malloc is not freed, and destructors are not executed. 

quit 

terminates the debugging session. The program calls exit (unless 
you started the debugger with the -startup option), 
quit -abort 

terminates the debugging session. The program does not call exit. 
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register Displays or modifies registers 
Synopsis register] [ register[[=]expression ]] 


Description If you do not specify any arguments, the register command displays 
the current contents of all the machine registers except floating-point 
registers. You can display integer, status, and flag registers, stack 
pointers, and instruction counters with the register command. If 
you specify a register, CodeProhe displays the contents of that register. 
If you also specify an expression, CodeProhe stores the value of that 
expression in the register. 

regs is a synonym for register. 

You can also use the display and set commands to display and 
modify the contents of registers. (You can use the fregister 
command to display floating-point registers. You can use the rf lag 
command to modify flag registers.) 


Examples register 

displays all registers and flags, 
register d5 = 30 
sets register D5 to 30. 
r d3 = index 

sets register D3 to the value of index, 
register aO Sx 

sets register AO to the value pointed to by x. 
r a 1 

displays the value stored in register Al. 

See Also display, fregister, rflag, set 
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restart 

Synopsis 

Description 


► Caution 


Restarts the program being debugged 
res [tart] [argument-list] 

The restart command reloads and executes your program up to the 
entry point of main, just as when the debugger was first invoked. If 
you do not specify any arguments, restart restarts the program with 
the same arguments that you specified when the debugger was first 
invoked. (If you started CodeProbe with the -startup option, 
execution stops before the startup code is executed and not at the first 
line of the main function.) Because the program is reloaded, all static 
data is reinitialized. All breakpoints are retained, and watch breaks on 
static and external variables are retained and disabled if: 

□ You linked with a startup module other than cres . o or 

catchres . o. 

□ The breakpoint or watch break is set on an item in the near data 

section. 

If you started CodeProbe with the -command option, do not use the 
restart command. Do not use the restart command as one of a 
sequence of commands separated by semicolons. 

If you specify arguments to the program, separate each argument 
with white space, just as the arguments would appear on the command 
line when invoking the program. The program uses these arguments as 
if they were specified on the command line. 

The restart command may cause your machine to crash if used 
improperly. 

When you enter the restart command, your program is immediately 
reloaded and re-executed with no cleanup other than calling the exit 
function to close files. The machine may be left in a state that can 
cause problems later. To avoid this problem, allow your program to 
run to completion, if possible, and do any necessary cleanup before 
entering the restart command. A 

The start and restart commands are the same if the same 
arguments are provided as the argument-list. The significant difference 
between the two commands is their behavior when they are specified 
with no arguments. The start command without an argument-list 
restarts the program without any arguments; however, the restart 
command without an argument-list restarts the program with the 
original arguments used when the debugger was invoked. 
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restart Restarts the program being debugged 
( continued ) 

Examples restart 

restarts the program using the same arguments with which it was 
initially invoked, 
restart myfile.txt 5 

restarts the program passing it two arguments: myfile.txt 
and 5. 

restart "sample string" 

restarts the program passing in a string as an argument. 

See Also start 
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return 

Synopsis 

Description 


► Caution 


Returns immediately from the current function 
ret[urn] [expression] 

The return command causes the current function to return to its 
caller without executing the rest of the function. 

Note: This command is not supported for C+ + programs. 

The value of the expression, if specified, is used as the return value 
from the function. The value is converted to the appropriate type if 
necessary. However, it must be a scalar quantity (not a structure or 
union). 

If register is the machine register that holds the return value, the 
return command is equivalent to the following: 

set register=expression", jump return; proceed 

When you enter the return command, the return value, if any, is 
returned to the calling function, and execution is suspended as though 
a breakpoint were triggered in the calling function after the call was 
made. For example, you may have the following code: 

i = 5; 

j = func(i); 
if (j < 2) 

j++; 

If a return 7 command is issued during the execution of f unc, 
execution stops inside the line that did the call, just before the 
assignment to j . You can then step to the next statement. 

An attempt to return a value from a function declared void is 
treated as an error, and an error message is displayed. Similarly, an 
error message is displayed if you use a simple return command 
(without an expression) from within a function declared as having a 
return value. In all other cases, the return value is cast (if necessary) 
to the correct type and returned to the calling function. 

Using the return command while stopped in the prolog of a 
function causes unpredictable results. 

A function prolog is code generated by the compiler at the start of each 
function. This code sets up the call frame and any automatic variables. 
If you have specified opt prolog off or if you step into a function 
in assembler mode, it is possible to stop inside the function prolog. 

▲ 
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return Returns immediately from the current function 
(continued) 

► Caution Do not use return in optimized code. 

The optimizer may have modified the data on the stack, and the 
debugger will not be able to find the return address. ▲ 

Examples return stringptr 

returns the value of stringptr. 
ret 5 

returns an integer value of 5. 
return 

returns from a void function. 
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rflag Displays or modifies flags 
Synopsis rf[lag] [flag-setting...] 

Description The rflag command can be used to display or modify the settings of 
the machine flags. If no parameters are specified, the current settings 
of the flags are displayed. With one or more arguments, the indicated 
flags are set or cleared according to the values given. 

A flag setting can be one of the values in the following table. The Set 
column contains the values used to set flags, while the Gear column 
contains the values used to clear flags. 


Flag Name 

Set 

Clear 

Overflow (yes/no) 

OV 

NV 

Sign (negative/positive) 

NG 

PL 

Zero (yes/no) 

ZR 

NZ 

Auxiliary Carry (yes/no) 

AC 

NA 

Carry (yes/no) 

CY 

NC 


Examples rflag 

displays all registers and flags, 
rflag cy 

sets the carry flag to 1 (yes). 
See Also fregister, register 
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search 

Synopsis 

Description 


Examples 


See Also 


Searches for a string in the current source file 
sea[rch] [string] 

The search command searches the current source file for the 
specified string. 

In windowing mode, the search begins from the top line of the 
current Source window. If the debugger finds a match, CodeProbe 
repositions the Source window so that the line containing the match is 
the number of lines specified by the opt context command from 
the top of the window. The cursor is positioned at the beginning of the 
matching string. 

In line mode, the search begins at the first line that would be 
displayed if you entered a 1 i s t command with no arguments. 
CodeProbe displays the line containing the match. 

If you do not specify any arguments, the debugger searches for the 
string specified in the last search command, starting from the new 
current line. If it does not find a match, CodeProbe prints a message. 

If you enter search again, the search resumes beginning at the top of 
the file. 

You can use the opt case command to specify whether the search 
is case sensitive. 

search foo 

finds the string "foo". 
search foo; 

finds the string "foo". The semicolon used in this command is a 
command delimiter and is not considered part of the search string, 
search foo\; 

finds the string "f oo ; ". The escape character (\) tells the 
debugger that the semicolon is part of the search string, 
search 

repeats the last search, 
opt, list 
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set 

Synopsis 

Description 


Examples 


Modifies the values of variables or memory locations 
se[t] variable 

s e [t ] register-name[=]expression 
se[t] a ddress[=]string 

The set command modifies the values of variables, registers, or 
memory locations in the program being debugged. 

Note: This command is not supported for C++ objects. 

If you specify a variable or register name and an expression, this 
command stores the result of expression in the location you specify. In 
this command, variable can be a reference to an array element or a 
structure member or an indirect reference. The variable cannot refer to 
an aggregate such as a structure, union, or array. Specifying a register 
name and expression is equivalent to: 

register register-name=expression 

If necessary, the value for variable will be converted to the proper type 
in accordance with the normal C conversion rules; it is then entered 
into memory at the address of the first variable operand. This is 
similar to a C assignment statement for a scalar variable. 

The register can be any valid register name, DO through D7 and AO 
through A7, and if a co-processor is present, FPO through FP7. You 
can use the $ prefix to distinguish the register from a variable of the 
same name. 

You can also use the set command to store a string into memory. 
The null terminator is not copied unless it is explicitly present in the 
string. The equal sign is optional. You can also use the built-in 
strcpy and memcpy functions to store a string in memory. 

You should use the built-in strcpy and memcpy functions instead 
of using set address = string. However, if you specify an address and a 
string, the set command stores the string at that address in memory, 
set does not copy the null terminator unless it is explicitly present in 
the string. 

set i = 5 

sets the variable i equal to the integer value 5. 
set a = 3.1415 

sets the variable a equal to the floating-point value 3 . 14 15. 
set $d0 = 300 

sets register DO equal to 300. The $ is optional. 
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Set Modifies the values of variables or memory locations 
(i continued ) 

set time->date = newtime 

sets the date member of the time structure equal to the value of 
the variable newtime. 

set stringptr "this string has no null byte" 

stores a string that is not null-terminated to the memory location 
pointed to by stringptr. 

set stringptr "this string has a null byte\0" 

stores a null-terminated string to the memory location pointed to by 
stringptr. 

set stringptr "string one\Ostring two\0" 

stores two null-terminated strings to the memory location pointed to 
by stringptr. 

See Also fregister, memcpy, strcpy, register 
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sleep 

Synopsis 

Description 

Example 


Pauses for the time specified 
sle[ep] number 

The sleep command pauses the debugger for the number of seconds 
specified by the number parameter. 

sleep 10 

pauses for 1 0 seconds. 
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show 

Synopsis 

Description 


Sets Source window to display specified source 

sh[ow] \module[\func] 
sh[ow] func [line] 
sh[ow] line 

The show command tells the debugger to display the specified source 
in the Source window. The current environment does not change. 
Specify the module, function, or line in the same format as that 
displayed by the env command. 

To return the Source window to the current environment, enter the 
env command without any parameters. 

show \sort . c\pr intArr 42 

moves the Source window to line 42 of the pr intArr function in 
the module sort.c. 


Example 
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source 

Synopsis 

Description 


Examples 
See Also 


Displays the source file 
so[urce] [filename] 

The source command overrides the C source file associated with the 
current module. The specified value for filename replaces the filename 
associated with the module for the rest of the current debugging 
session. CodeProbe displays the new file immediately and echos its 
name in the Dialog window. 

If you do not specify a filename, the name of the current source file 
is echoed in the Dialog window but the current source file is not 
changed. The file is reread from disk if it has changed. 

If the filename to which you want to change is the same as the 
default filename but the path is different, you can use the 
opt search command instead of the source command to change 
the locations where CodeProbe looks for source files. The 
opt search command affects all source files, not just the current 
one. 

source 

displays the current filename, 
source test/testi. c 

changes the filename for the current module to t e s 1 1 . c in the 
test directory. 

opt 
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start 

Synopsis 

Description 


► Caution 


Restarts the program being debugged 
sta[rt] [ argument-list ] 

The start command reloads and executes your program up to the 
entry point of main, just as when the debugger was first invoked. If 
you do not specify any arguments, start restarts the program with 
the same arguments that you specified when the debugger was first 
invoked. (If you started CodeProbe with the -startup option, 
execution stops before the startup code is executed and not at the first 
line of the main function.) Because the program is reloaded, all static 
data is reinitialized. All breakpoints are retained, and watch breaks on 
static and external variables are retained and disabled if: 

□ You linked with a startup module other than cres . o or 

catchres . o. 

□ The breakpoint or watch break is set on an item in the near data 

section. 

If you started CodeProbe with the -command option, do not use the 
start command. Do not use the start command as one of a 
sequence of commands separated by semicolons. 

If you specify arguments to the program, separate each argument 
with white space, just as the arguments would appear on the command 
line when invoking the program. The program uses these arguments as 
if they were specified on the command line. 

The start command may cause your machine to crash if used 
improperly. 

When you enter the start command, your program is immediately 
reloaded and re-executed with no cleanup other than calling the exit 
function to close files. The machine may be left in a state that can 
cause problems later. To avoid this problem, allow your program to 
run to completion, if possible, and do any necessary cleanup before 
entering the start command. ▲ 

The start and restart commands are the same if the same 
arguments are provided as the argument-list. The significant difference 
between the two commands is their behavior when they are specified 
with no arguments. The start command without an argument-list 
restarts the program without any arguments; however, the restart 
command without an argument-list restarts the program with the 
original arguments used when the debugger was invoked. 
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Start Restarts the program being debugged 
(continued) 

Examples start 

restarts the program being debugged without passing it any 
arguments. 

start myfile.txt 5 

restarts the program being debugged passing in the arguments 
myfile.text and 5. 

See Also restart 
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symbol 

Synopsis 

Description 

Example 
See Also 


Finds the symbol nearest to the specified address 
symb[ol] address 

The symbol command searches the symbol information and displays 
the name of the symbol whose location is closest to the address 
specified by the address parameter. 

symbol 0x7D9F884 

displays the symbol whose address is nearest to 0x7D9F884. 
symload 
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symload Loads debugging information for an executable file 

Synopsis sy[mload] 

sy[mload] " executable-filename " 

sy[mload] pc address [ n executable-filename "] 

sy[mload] proc "proc-name" | proc-address [" executable-filename "] 

sy[mload] seg address " executable-filename " 

Description The symload command associates an executable file and any 

debugging information found in that file with a load module. The 
symload command is useful when you are debugging several 
interacting programs that are invoked from separate executable files. 
This command does not load any code into memory or spawn any new 
processes or tasks. 

If you do not specify any options and you are running SegTracker, 
symload asks SegTracker for the seglist and filename based on the 
current PC. symload then loads the debugging information from the 
file if it is available. 

If you specify an executable-file without any other options and you 
are debugging a process, the symload command gets the seglist from 
the current process CLI if the process was started from the Shell or 
from the current Process structure if the process was started from the 
Workbench, symload then loads the debugging information from the 
filename in the seglist. If the PC is not in the seglist, symload prints 
a message saying that the debugging information was loaded properly, 
but the program is probably in an operating system call. (This option is 
useful if you want to catch programs that are in a Wait system call.) 

The symload command supports the following options: 

pc 

asks SegTracker for the seglist and filename based on the address 
that you specify. If you also specify an executable-filename, then 
symload loads the debug information associated with that file 
instead of looking for the file associated with the process, 
proc 

uses the process name or address to find the CLI structure (if the 
program was invoked from the Shell) or the current Process 
structure (if the program was started from the Workbench), 
symload gets the seglist and command name from the CLI or 
Process structure. If you specify a process name, enclose the name 
in double quotes (" "). If the process name is not unique, 
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symload 

(continued) 


Examples 


See Also 


Loads debugging information for an executable file 


symload uses the first process with that name in its list. If you 
also specify an executable-filename, then symload loads the debug 
information associated with that file instead of looking for the file 
associated with the process, 
seg 

treats the hexadecimal address you specify as a pointer to a BCPL 
segment list and maps the list to the executable file you specify. 

symload "myapp" 

reads the current segment list and symbols from the file named 
myapp. 

sym proc "myapp" 

reads the segment list and executable file for process myapp. 
symload proc 0x7D9F884 "myapp" 

reads the segment list and executable file for the process located at 
0x7D9F884. 

symload seg 0x7D9F884 "myapp" 

uses the segment list at address 0x7D9F884. 

hunks 
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tasks Displays a list of system tasks 
Synopsis ta[sks] [a[ll]] 

Description The tasks command displays information about tasks. By default, 
tasks displays the tasks currently under debugger control. If you 
specify all, this command displays the list of all system tasks. 

The opt task command displays information in the following 
format: 

Address Type Pri State SigWait StackPtr Debug Name 

00C513B8 13 0 Waiting 80000000 00C551CC act multi 

The fields contain the following information: 

Address contains the address of the task control block. 

Type indicates the type of node that begins the task control 
block. The number 13 is used for processes, and 1 is 
used for simple tasks. For a complete list of the possible 
task types, see the header file 
include : exec /nodes . h. 

Pri contains the priority of the task. 

State indicates the process state: Waiting or Ready. 

SigWait displays the SigWait field of the task control block. 

This field indicates which signal bits the task may be 
waiting on. 

StackPtr is the current position of the stack pointer. This value 
will be different from the value displayed in the SP 
register. The value displayed by tasks includes any 
information placed on the stack by the trap handler or 
exception handler associated with this task. 

Debug indicates the task’s status with the debugger: act 

denotes an active task, and inact denotes an inactive 
task. This field is blank for tasks that are not under the 
control of the debugger. 

Name is the name of the task as specified in the task’s node 
structure. 

For more information on tasks or on any of these fields (except 
Debug), refer to the Amiga ROM Kernel Reference Manual: Libraries 
and Devices. 
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tasks Displays a list of system tasks 
( continued ) 

Examples tasks 

displays a listing of all tasks under debugger control, 
ta all 

displays a listing of all tasks in the system. 


See Also activate, catch, deactivate, detach, opt 
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trace 

Synopsis 

Description 


Examples 
See Also 


Single-steps into function calls 
t[race] [integer] 

In C mode, the trace command steps the number of source 
statements specified by the integer parameter. In Mixed or Asm 
modes, it steps the number of machine instructions specified by the 
integer parameter. If CodeProbe encounters a function call, stepping 
continues into that function. If you do not specify an integer, trace 
steps one line. 

You can also enter the trace command by pressing the F7 key. 

When you are debugging a C+ + program in C source mode, the 
trace command steps over the translated C statements. In other 
words, if one C+ + statement was translated into more than two C 
statements, it will require two trace commands to step over the 
C+ + statement. 

trace 

steps one source statement if in C mode, or one machine instruction 
if in Mixed or Asm mode, 
t 5 

steps five source statements or machine instructions, 
go, proceed, ps, ts 
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ts 

Synopsis 

Description 


Examples 
See Also 


Single-steps by source line into function calls 
ts [integer] 

The ts command is similar to the trace command, except that ts 
steps only by C source line, even if the source mode is set to Asm or 
Mixed. The integer parameter specifies the number of C source lines 
to step. If you do not specify an integer, t s steps one line at a time. 

When you are debugging a C + + program in C source mode, the ts 
command steps over the translated C statements. In other words, if 
one C++ statement was translated into more than two C statements, 
it will require two ts commands to step over the C+ + statement. 

ts 

steps one source line regardless of the mode the debugger is in. 
ts 2 

steps two source lines, 
proceed, ps, trace 
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unalias 

Synopsis 

Description 

Examples 


Deletes an alias 

una[lias] name 
una[lias] * 

The unalias command removes entries from the debugger’s list of 
aliases. To remove a specific alias, specify the alias name. To remove 
all aliases, specify an asterisk (*). 

unalias foo 

deletes the alias for foo. 
una * 

deletes all abases. 


See Also alias, define, undefine 
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unassemble 

Synopsis 

Description 


Examples 


Displays memory as assembler instructions 
unassemble] [start-location [ end-location ]] 

The unassemble command displays the range of memory from start- 
location to end-location in assembler format. 

If you do not specify a location, unassemble disassembles the 
memory at the address in the current program counter. If you specify 
only a start-address , unassemble displays the memory at that 
address. 

If you enter additional unassemble commands before giving the 
program control with a trace, proceed, or go command, 
unassemble continues disassembling from the location at which the 
previous unassemble command stopped. 

If the debugging information contains source line numbers for the 
memory being displayed, unassemble displays the C source line and 
the assembler instructions generated for that line. If the debugging 
information does not contain source line numbers for the memory 
being displayed, unassemble displays the number of instructions as 
specified by the opt unassemble command. By default, 
unassemble displays 4 instructions. 

The output of the unassemble command is equivalent in format to 
output displayed in the Source window if you are in asm mode. The 
output consists of three or four fields depending on the setting of the 
instruction bytes option, which is controlled by the opt i bytes 
command. The following is an example of unassemble output with 
instruction bytes on and source unavailable: 

0x25F950 48E70130 MOVEM.L D7/A2-A3,-(A7) 

0X25F954 BFEC0004 CMPA.L 0004 (A4 ) , A7 

0X25F958 65001BD6 BCS 00261530 

The first field contains the hexadecimal address of the instruction 
being disassembled. The second field is a hexadecimal dump of the 
actual bytes composing the instruction. The third field contains the 
M680x0 mnemonic for the given opcode. The fourth field contains the 
operands to the instruction. If the ibytes option is turned off, the 
second field is not displayed. 

unassemble \mod1\fund 10 

unassembles line 10 of fund in modi, 
unassemble 13 14 

unassembles lines 13 to 14. 
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unassemble 

(continued) 


Displays memory as assembler instructions 


unassemble fund 

unassembles the first line of fund. 

unassemble fund func2 

unassembles from Sfuncl to Sfunc2. 

unassemble 

continues unassembling at the last location. 


See Also opt, list 
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undefine 

Synopsis 

Description 

Examples 
See Also 


Deletes a macro definition 

[#]und[efine] name 
[#]und[ef ine] * 

The undefine command removes entries from the debugger’s list of 
macro definitions. To remove a specific macro, specify the macro name. 
To remove all defines, specify an asterisk (*). 

The # sign is optional and allows the debugger to read C header files 
(.h files) using the execute command. 

#undef foo 

deletes the macro named foo. 
undefine * 

deletes all macros. 

alias, define, execute, unalias 
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watch 

Synopsis 

Description 


Examples 


See Also 


Sets a watch on a variable or memory 

w[atch] expression | range [s[tatic] | d[ynamic]] 

The watch command sets a watch for the expression or memory range 
specified. A watch allows you to monitor a variable, an address, or a 
range of memory. Whenever control returns to the user, for example 
by stepping or stopping at a breakpoint, the new value of the watched 
object is displayed in the Watch window. The Watch window can be 
opened with the View menu, the window command, or by pressing 
the FI key. 

In line mode, the object is not automatically displayed. You must use 
the wlist command to display it. 

Note: This command is not supported with C+ + objects. 

The watch command does not stop program execution when the 
value being watched changes; it just displays the changed value. Use 
the wbreak command if you want program execution to stop when 
the watched value is changed. 

By default, watches are dynamic. The expression being watched is 
re-evaluated whenever control returns to the debugger. For example, 
watch tmp [ i ] causes the watch to move every time i changes. 

The static option evaluates the expression only once, when the 
watch is set. The static option treats the result as an address, and 
displays the contents of the memory at that address. 

watch text->len 

sets a watch for the symbolic scalar text->len. 
w \mod\f 1 \ a [ 0 ] L 20 

sets a watch for a length of 2 0 bytes starting at the symbolic range 

specified by \mod\ f 1 \ a [ 0 ] . 
w Sa [ 0 ] .. S a [ 5 ] 

sets a watch for the range from & a [ 0 ] to £ a [ 5 ] . 
watch tmp [ i ] static 

if i = 3, watches tmp [ 3 ] regardless of changes to i. 
wbreak, wclear, wdisable, wenable, wlist 
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wbreak 

Synopsis 

Description 


Examples 


See Also 


Sets a watch break 

wb[reak] expression | range [s[tatic] | d[ynamic]] 

The wbreak command sets a watch break for the expression or 
memory range specified. Whenever any byte in a specified range is 
modified, control is returned to you. 

Note: This command is not supported with C+ + objects. 

By default, watch breaks are static. The expression is evaluated 
once when the watch break is set. The debugger treats the result as an 
address, and displays the contents of the memory at that address. 

The dynamic option re-evaluates the expression or range whenever 
control returns to the debugger. For example, wbreak tmp[ i ] 
causes the watch break to break every time i changes. 

wbreak text->len 

sets a watch break for the symbolic scalar text->len. 
wb \mod\f 1 \ a [ 0 ] L 20 

sets a watch break for a length of 2 0 bytes starting at the symbolic 
range specified by \mod\f 1 \a [ 0]. 
wbreak Sa [ 0 ] . . Sa [ 5 ] 

sets a watch break for the range from S a [ 0 ] to s a [ 5 ] . 
wb p->q dynamic 

sets a watch break for different locations depending on the value of 
P- 

watch, wclear, wdisable, wenable, wlist 
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wclear 

Synopsis 

Description 


Examples 


See Also 


Clears (deletes) one or more watches 

wc[lear] integer [integer ...] 
wc[lear] * | l[ast] 
wc[lear] integer, .integer 

wclear command clears (deletes) one or more watches or watch 
breaks. When a watch or watch break is cleared, it ceases to exist and 
can be reinstated only by entering the watch or wbreak command 
again. To disable watches or watch breaks temporarily, use the 
wdi sable command. 

The integer parameter specifies the watch or watch break number as 
displayed by the wlist command. You can specify as many watch or 
watch break numbers as needed. An asterisk (*) clears all watches and 
watch breaks, and last clears only the most recently set watch or 
watch break. You can specify a range of watches or watch breaks with 
integer, .integer. 

wclear 256 

clears watches or watch breaks numbered 2, 5, and 6. 
wclear last 

clears the last watch or watch break set. 
wc * 

clears all watches or watch breaks. 
wc4 . .7 

clears watches 4, 5, 6, and 7. 
watch, wbreak, wclear, wdisable, wlist 
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wdisable 

Synopsis 

Description 


Examples 


See Also 


Disables (turns off) one or more watches 

wd[i sable] integer [integer...] 
wd[isable] * | l[ast] 
wd[isable] integer . . integer 

The wdisable command disables (turns off) one or more watches or 
watch breaks. When a watch or watch break is disabled, it is not 
recognized by CodeProbe, but it remains on the list of current watches 
or watch breaks. 

The integer parameter specifies the watch or watch break number as 
displayed by the wlist command. You can specify as many watch or 
watch break numbers as needed. An asterisk (*) disables all watches 
and watch breaks and last disables only the most recently set watch 
or watch break. You can specify a range of watches or watch breaks 
with integer . . integer. 

To re-enable a disabled watch or watch break, use the wenable 
command. 

wdisable 256 

disables watches or watch breaks numbered 2, 5, and 6. 
wdisable last 

disables the last watch or watch break set. 
wdisable * 

disables all watches or watch breaks, 
wdisable 4 . . 7 

disables watches 4, 5, 6, and 7. 

watch, wbreak, wclear, wenable, wlist 
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wenable 

Synopsis 

Description 


Examples 


See Also 


Enables (turns on) one or more watches 

we[nable] integer... 
we[nable] [* | l[ast] 
we[nable] integer, .integer 

The wenable command enables (turns on) one or more watches or 
watch breaks that have been disabled by the wdi sable command. 

The integer parameter specifies the watch or watch break number as 
displayed by the wlist command. You can specify as many watch or 
watch break numbers as needed. An asterisk (*) enables all watches 
and watch breaks and last enables only the most recently set watch 
or watch break. You can specify a range of watches or watch breaks 
with integer, .integer. 

we 2 5 6 

enables watches or watch breaks numbered 2, 5, and 6. 
we last 

enables the last watch or watch break set. 
wenable * 

enables all watches or watch breaks, 
we 4 . . 7 

enables watches 4, 5, 6, and 7. 
watch, wbreak, wclear, wdisable, wlist 
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whatis 

Synopsis 

Description 


Examples 


Determines the type of an object 

wha[tis] expression 
wha[tis] [type) 

The whatis command displays the type, location, and storage class of 
an object or gives additional information about a data type. If you 
specify an expression, whatis displays the C data type of the 
expression. If the result of the expression is a simple variable or a 
member of an array, whatis displays the address of the object and 
identifies it as either static, extern, or automatic. If the result 
of the expression is a function, whatis displays the address of the 
function, its return type, and its location. 

If you specify a type, whatis displays the full definition for the 
type. For struct, union, and enum types, the debugger displays all 
members of the aggregate. For a type that has been defined by a 
typedef statement, the debugger displays the base type of the 
typedef . You can also specify basic C data types such as int or 
long as the type. 

This command is not supported for C++ names. Use the listsym 
command to display the mangled C name, and specify the C name as 
the parameter to whatis. 

whatis i 

determines the type of a variable named i. 
wha main 

determines the type, address, and defining module for the main 
function. 

wha 3 . 5 

determines the type of a constant, 
whatis Red 

determines the type of an enumeration constant, 
wha *p->c [ 3 ] 

determines the type of the expression *p->c [ 3 ] . 
whatis (int) (1*3.4) 

determines the type of an expression with a type cast, 
whatis (node) 

determines the type of a typedef. 
whatis (struct X) 

displays the members of struct X. 
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where 

Synopsis 

Description 


Examples 


See Also 


Shows the calling sequence 
whe[re] [a[rgs]] [integer] 

The where command displays a list of the function calls in the call 
sequence. Calls are listed in reverse order beginning with the most 
deeply nested function. For example, if main calls firstfunc at line 
92, firstfunc calls nextone, and nextone calls innermost at 
line 68, the output from the where command would look like this: 

1 In routine fpreg. o:\fpreg.c\innermost 48 

2 * Called from fpreg. o:\fpreg.c\nextone 68 (+0xE) 

3 Called from fpreg. o: \fpreg.c\f irstfunc 82 

4 Called from fpreg. o:\fpreg.c\main 92 

The numbers on the left indicate a level number that can be passed to 
the env command. Level 1 is the run environment or the function in 
which you are currently stopped. The caller’s level is 2, its caller is 3, 
and so on. These level number designations change over time as the 
program steps into and returns from functions. The asterisk indicates 
the current user environment as set by the env command. 

The args option displays the arguments to each function like the 
args command. 

The integer parameter specifies the number of calls to be displayed. 
By default, only the 20 most recent calls are printed. 

You can also display the calling sequence by opening the Calls 
window. 

The Calls window also displays this information, 
whe 

displays a list of the last 20 function calls, 
where 5 

displays a list of the last 5 function calls, 
where a 

displays the arguments to each function, 
args, env 
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window 

Synopsis 

Description 


Opens or closes a window 
wi[ndow] window-name [on | off] 

The window command opens or closes the specified window. You can 
specify any of the following window-names: 


c[alls] mo[dules] w[atch] 

he[lp] ms[g] s[ource] 

me[mory] r[egister] 

If you do not specify on or off, the window command toggles the 
specified window. (If the window is currently opened, the window 
command closes it, and if it is currently closed the window command 
opens it.) 

If you specify on and the name of a window that is already open, 
the specified window pops to the foreground. 

The window command is ignored in line mode. 

Examples wi register 

toggles the Register window, 
window help on 

opens the Help window or pops it to the top. 
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wlist 

Synopsis 

Description 


Example 
See Also 


Lists all watches 
wl[ist] 

The wlist command displays a list of all watches and watch breaks, 
wlist displays the list of all watch and watch breaks, as shown in the 
following example: 

1 <dynamic> i : 42 (0x2A) 

2! <static register> d : 21 
3 * <dynamic> q : 14 (OxOE) 

The numbers 1, 2, 3, and 4 are watch or watch break numbers. You 
can use these numbers to identify a specific watch or watch break in 
the wclear, wdisable, and wenable commands. If the number is 
followed by an asterisk (as with number 3), the watch or watch break 
is disabled. An exclamation point ( ! ) indicates a watch break. 

Following the number is a description of the watch or watch point. In 
the above example, watch number 1 is a watch on the variable i, and 
its current value is 42 (0x2A in hexadecimal). 

wlist 

lists all watches. 

watch, wbreak, wclear, wdisable, wenable 
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wmsg 

Synopsis 

Description 

Examples 


Writes a message to the Message window 
wmsg integer message-text 

The wmsg command writes the text specified by the message-text in the 
Message window. The integer parameter specifies the line number in 
the window for the text. Line 0 is the top line. This command is used 
primarily with AREXX scripts. 

wmsg 0 This is the Message window. 

displays the string This is the Message window. 

on the top line of the Message window, 
wmsg 12 This goes on line 12. 

displays the string This goes on line 1 2 . on line 12 of the 
Message window. 
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Using CodeProbe’s Built-in Functions 

The debugger’s built-in functions share the same names and the same 
functionality as the SAS/C library’s built-in functions. However, the 
debugger’s built-in functions are actually different functions. 

The library’s built-in functions are standard, commonly used 
functions recognized by the compiler and expanded inline for 
efficiency. CodeProbe cannot access these functions. Also, the library’s 
built-in functions are ANSI Standard functions. The SAS/C library’s 
built-in functions are described in Chapter 4, “Using the System 
Header Files to Access Libraries,” in the SAS/C Development System 
Library Reference. 

CodeProbe’s built-in functions provide functionality not available 
through other debugger commands, and you can use the debugger’s 
functions in the call and display commands. The debugger’s 
built-in functions are slightly different from the library’s built-in 
functions. For example, passing NULL to a built-in function is an error 
in CodeProbe. Overlapping memory blocks may be handled differently. 
Also, the parameters to CodeProbe’s built-in functions are more 
flexible than the parameters to the library’s functions: 


Formal Type 

Actual Parameter Types Allowed 

void * 

constant, register, any pointer scalar, array, 
function, address, string constant 

char * 

constant, register, character pointer, unsigned 
character pointer, character array, string 
constant 

int 

constant, register, any integral scalar, bitfield, 
enumerated constant 


Floating-point constants and registers are not allowed, and string 
constants can only be specified as the source operand. 

Some of these functions may take a long time to execute. You can 
interrupt a function by pressing Control-C. 

CodeProbe has a built-in # define statement that causes all 
references to the built-in functions to be referenced as 

buil tin —function, which is the actual name of the CodeProbe 

function. If you want to step into or call an actual function in your 
code that has the same name as a built-in function, you should use the 



undefine command to clear the #define or use the back quote 
character to escape the function’s name. 


Summary of Built-in Functions 

This section describes the following built-in functions: 


raemcmp 

compares two memory blocks 

memcpy 

copies a memory block (non-overlapping) 

menunove 

copies a memory block (possibly overlapping) 

memset 

sets memory to a specified value 

strcat 

concatenates two strings 

strcmp 

compares two strings 

strcpy 

copies a string 

str len 

returns the length of a string. 


Built-in Function Reference 


This section describes each of the CodeProbe commands. The 
commands are listed in alphabetical order. Each command and 
function description includes the following sections (if applicable): 


Synopsis 

Description 

Examples 
See Also 


shows the declaration for the function, including any 
header files that must be included in the calling routine, 
describes what the function does and contains all the 
information you need to use the function, 
contains example code showing how to use the function, 
refers you to the descriptions of functions that contain 
related information. 
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memcmp Compares two memory blocks 

Synopsis i = memcmp ( a , b , n ) ; 

int i; /* comparison results */ 

void *a, *b; /* blocks being compared */ 

int n; /* block size in bytes */ 


Description The memcmp function compares two memory blocks and returns a 
value whose sign indicates the collating sequence of the blocks, as 
follows: 


Return Meaning 

Negative First block below the second 

Zero Blocks are equal 

Positive First block above the second 


Examples display memcmp(ptr1, ptr2, n) 

displays the result of comparing ptr 1 and ptr2 for n bytes, 
b 27 when ( memcmp ( ptr 1 , ptr 2, 10) < 0) 

breaks at line 27 when the 10 bytes pointed to by ptr 1 evaluate to 
a value less than the value of the 10 bytes pointed to by ptr 2. 


See Also memcpy, memmove, memset 
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memcpy 

Synopsis 

Description 

► Caution 
Examples 


See Also 


Copies a memory block (non-overlapping) 

to = memcpy(to, from, n); 
void *to; /* destination pointer */ 

void *from; /* source pointer */ 

int n; /* block size in bytes */ 

The memcpy function copies data from one memory block to another. 
The memcpy function cannot be used to copy overlapping memory 
blocks. You should use the memmove function when copying 
overlapping blocks. 

This function produces unpredictable results if there is not enough 
memory to hold the data at the destination memory location. 

On some systems, you can crash your machine. A 

call memcpy(ptr1, 6j, 10) 
copies 10 bytes from ptr2 to ptrl. 
call memcpy ( 0x804a , myptr , 50) 

copies 50 bytes from myptr to location 0x8 04a. 
b 27 (memcpy(a0, al, 15)} 

sets a breakpoint at line 27 with an action to copy 15 bytes from 
the memory pointed to by register Al to the memory pointed to by 
register A0. 

memcmp, memmove, memset 
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memmove 

Synopsis 

Description 
► Caution 

Examples 


Copies a memory block (possibly overlapping) 

to = memmove(to, from, n); 
void *to; /* destination pointer */ 
void *from; /* source pointer */ 

int n; /* block size in bytes */ 

The memmove function copies data from one memory block to another. 
Overlapping blocks are handled correctly. 

This function produces unpredictable results if there is not enough 
memory to hold the data at the destination memory location. 

On some systems, you can crash your machine. ▲ 

call memmove ( ptr 1 , Sj, 10) 
copies 10 bytes from ptr 2 to ptr 1. 
call memmove ( 0x8 04a , myptr, 50) 

copies 50 bytes from myptr to location 0x8 0 4a. 
b 27 (memmove(a0, al, 15)} 

sets a breakpoint at line 27 with an action to copy 15 bytes from 
the memory pointed to by register Al to the memory pointed to by 
register A0. 


See Also memcpy, memcmp, memset 
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memset 

Synopsis 

Description 
► Caution 

Examples 
See Also 


Sets memory to a specified value 
to = memset (to, c, n) ; 

void *to; /* base of memory to be initialized */ 
int c; /* initialization value */ 

int n; /* number of bytes to be initialized */ 

The memset function sets the specified number of bytes of memory to 
the specified value. 

This function produces unpredictable results if there is not enough 
memory to hold the data at the destination memory location. 

On some systems, you can crash your machine. A 

call memset(ptr, 0, 100) 

sets 100 bytes to 0 starting at the address pointed to by ptr. 

call memset(a0, 'X', 50) 

sets 50 bytes to the ASCII character X starting at the address 
pointed to by register A0. 

memcpy, memcmp, memmove 
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strcat 

Synopsis 


Description 


► Caution 


Examples 


Concatenates two strings 

to = strcat(to, from); 

char *to; /* destination pointer */ 

char *from; /* source pointer */ 

The strcat function copies data from one string to the end of 
another string until a null character is found. Do not use strcat to 
copy overlapping strings. 

This function produces unpredictable results if there is not enough 
memory to hold the data at the destination memory location. 

On some systems, you can crash your machine. ▲ 

call strcat (myptr , "foo") 

concatenates the string "foo" after the string pointed to by the 
variable myptr. 


See Also strlen, strcmp, strcpy 
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Strcmp Compares two strings 

Synopsis i = strcmp(a, b); 

int i; /* comparison result */ 

char *a, *b; /* strings being compared */ 

Description The strcmp function compares two strings and returns a value whose 
signs indicate the collating sequence of the blocks as follows: 

Return Meaning 

Negative First string below the second 

Zero Strings are equal 

Positive First string above the second 


Examples display strcmp( "abc" , "def") 

tests the strings "abc" and "def" and displays the return value. 
The value indicates whether the strings are equal or which string is 
higher. 

break myfunc when ( strcmp ( arg , "foobar") == 0) 

breaks at the function myfunc when the variable arg points to the 
string "foobar". 


See Also strlen, strcpy, strcat 
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strcpy 

Synopsis 

Description 
► Caution 
Examples 
See Also 


Copies a string 

to = strcpy(to, from); 

char *to; /* destination pointer */ 

char *from; /* source pointer */ 

The strcpy function copies data from one string to another until a 
null character is found. Do not use the strcpy function to copy 
overlapping strings. 

This function produces unpredictable results if there is not enough 
memory to hold the data at the destination memory location. 

On some systems, you can crash your machine. ▲ 

call strcpy(a, b) 

copies the string pointed to by b to the memory location pointed to 
by a. 

strlen, strcmp, strcat 
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Strlen Returns the length of a string 

Synopsis len = strlen(s); 

int len; /* length of string s */ 

char *s; /* string to scan for length */ 


Description The strlen function returns the length of a string, as determined by 
the index of the first null character found. 

Examples display strlen( "hello" ) 

displays the length of the string "hello", which is 5. 
display strlen ( 0x8 04a ) 

displays the length of the string starting at address 0x8 0 4a. 


See Also strcmp, strcpy, strcat 
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Utility Reference 


This chapter describes the utilities included with the SAS/C 
Development System. The utilities are described in alphabetical order. 
The description of each utility includes each of the following sections, 
if applicable: 


Synopsis 

Description 

Example 

Error 

Messages 


shows the format of the command that invokes the 
utility 

describes what the utility does and contains all the 
information you need to use the utility 
contains examples that illustrate how to use the utility 
describes the error messages, if any, produced by the 
utility and the action required to fix the error. 
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COVGf Analyzes coverage data 
Synopsis cover [ options ] [datafile]. . . 

Description The cover utility analyzes the coverage data produced when you 

compile and run your program with the coverage option. Using this 
data, you can determine which lines of code in your program were 
executed and which were not. This information can help you design 
test cases that exercise all of the lines in your code. 

When you run your program, it writes coverage data to the file 
cover.dat in the current directory. If this file does not exist, your 
program creates it. If this file already exists, your program reads in 
the existing cover.dat, merges in the new coverage data, and writes 
the merged data back to cover.dat. 

This utility analyzes the coverage data file, locates your C source 
files, and produces new output files containing a copy of your C source 
with arrows pointing to lines that generated code that was not 
executed. The output file has the same basename as the C source file, 
but with the extension . cov instead of . c. 

By default, cover looks for the coverage data file cover.dat in 
the current directory. If you choose to rename cover.dat, you must 
specify datafile when you run cover. 

To use cover, follow these steps: 

1. Compile your program with the coverage option. Specifying 
coverage slows down your program considerably, so do not 
specify coverage for production software. You can choose to 
compile only certain modules with coverage to reduce 
overhead. 

2. Link your compiled program with the appropriate library for 
your options, such as sc . lib or senb. lib, and with one of 
the startup files supplied by the SAS/C Development System, such 
as c . o or cres . o. 

3. Run your program normally to create cover.dat. 

4. Run the cover utility. 

If you link your program using the link option in the sc command, 
the linker automatically links your program with the startup file c . o 
and with the appropriate library. For example, the following command 
produces an executable named my prog that is ready for coverage 
analysis: 


sc cover link rayprog.c 
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Cover Analyzes coverage data 
(continued) 

You can use the startup option to specify a different startup file. If 
you are linking using a separate slink command, you must specify 
both the appropriate startup file and library. 

When you compile with the coverage option, autoinitialization and 
autotermination functions are linked in from the library to initialize 
and terminate coverage analysis. The cover autoinitialization and 
autotermination functions run at priority 210. Autoinitialization 
functions and autotermination functions with a priority number that is 
less than 210 will not be included in the coverage data. For more 
information about autoinitialization and autotermination functions, 
refer to Chapter 10, “Using Startup Modules, Autoinitialization, and 
Autotermination Functions,” in SAS/C Development System User’s 
Guide, Volume 1: Introduction, Compiler, Editor. 

The cover utility supports the following options: 

dir = directory-pathname 

specifies the directory path or paths to search to locate the C source 
files. The coverage data contains the name of the C source file, but 
not its directory. If the C source file is not in the current directory, 
specify the dir= option with the proper directory as its argument. 
To specify multiple pathnames, separate each pathname with a plus 
( + ) sign or a comma (,). Also, you can specify dir as many times 
as necessary, 
merge filename 

tells cover to read the specified data files, merge the information 
contained in them, and write the merged data to filename. If you 
specify merge, cover does not look for C source files and does not 
produce a report. This option allows you to combine the results of a 
suite of tests to determine what code is exercised by the test suite as 
a whole, 
nosource 

tells cover not to read in the C source files. Instead, it prints a 
report to the Shell window listing the names of all source files and 
the lines in each file that were not executed. 

Example The sc : examples drawer contains a program named lines . c. To 
analyze the coverage of this program, open a Shell, copy lines . c to 
a working directory, use the cd command to change to the working 
directory, and enter the following command: 


sc lines. c coverage link 
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cover Analyzes coverage data 
(continued) 


The compiler produces a program called lines. Run this program 
with no command-line options: 

lines 

Watch the lines for a few seconds, then click on the close gadget to 
terminate the program. The program produces a file called 
cover . dat. Run the cover utility on this file: 

cover 

The cover utility reads cover .dat and lines . c and writes the 
file lines . cov. Use your editor to examine lines . cov. Lines that 
were not executed are highlighted with an arrow (= = >) in the left 
margin. 

Refer to the sc : examples /cover directory for an example 
program that uses cover. 
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demangle 

Synopsis 

Description 


Example 


Converts C names into C+ + names 
demangle C-name [C-name]... 

The demangle utility converts the specified C names that were 
generated by the C+ + translator into their original C+ + forms. 

The C+ + language recognizes different rules for names than does 
the C language. The C+ + translator must compile C+ + names into C 
names in such a way that it does not create duplicate C names. To 
create a C name, the translator incorporates the name of the class, the 
name of the function, and the types of all of the parameters to the 
function. If the function is a member function, the translator separates 
the class name from the rest of the name with two underscores ( ). 

If you run sc with the cxxonly option, the resulting . . c file 
contains C names that were generated by the translator. To read this 
file, you may need to use the demangle utility to convert the C 
names. 

If you compiled with the debug option, the debugging information 
in the object module refers to the names generated by the translator. 

In many cases, the debugger can also display the C+ + name. If you 
want to run the debugger from an AREXX script, you may need to use 
demangle to convert the C names. 

> demangle bar — 3foo 

foo: :bar 

bar 3 foo is the mangled C name as it would appear in the 

generated . . c file, f oo : : bar is the demangled C+ + name as it 
would appear in your C+ + source file. 
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diff Determines the differences between two files 
Synopsis diff [> destination] [ options ] Riel file2 

Description The diff utility determines the differences in contents between two 
files and describes the lines that you should delete from, add to, or 
change in Rle2 to make it look like Riel. To help you find those lines, 
diff identifies the line numbers and gives the text of the lines. 

If you enter the diff command without specifying filenames, diff 
displays the version that you are using and describes the options 
available. 

Output from this utility is sent to the standard output device, unless 
you redirect it by specifying the -o option or by entering a greater 
than (>) sign followed by a destination. 

diff supports the following options: 

-bnn sets the size of the I/O buffer to the value specified by nn. The 
default I/O buffer size is 4K, and the maximum size is limited 
by the amount of available system memory. Increasing the size 
of the I/O buffer makes diff run faster. 

- c displays only those lines common to both files. 

-F nn sets the column number where you want diff to begin 
comparing lines. For example, if you set nn to 25, diff 
ignores the first 25 characters on each line. 

-L nn sets the column number where you want diff to stop 
comparing lines. For example, if you set nn to 75, diff 
ignores the characters beyond column 75 on each line. 

-Inn defines the number of lines, nn, per file that can be handled 
by diff. diff uses two tables (one for each file) to keep 
track of the fines read in from each file. The default size of 
each of these tables is 2000; the maximum number is limited 
by memory availability. If diff is running out of memory 
and your files are less than 2000 fines in length, you can use 
this option to increase the amount of memory available, or 
you can check to see if any other tasks are running 
concurrently and shut down any unwanted tasks. 

-oRle sends the output to the specified file (or device). You can use 
this option instead of the AmigaDOS redirection command. 

You can send the output to a different device by specifying the 
device name. For example, to send output to the printer, 
specify -oprt : . To send output to a file on drive df 0 : , 
specify -odf 0 : filename. 



Utility Reference 213 


diff Determines the differences between two files 
(continued) 


-p filters out unprintable characters from the input stream. You 
can use this option to clean out an AmigaDOS binary file. 

-q suppresses any messages if there are no differences between 
the specified files. 

-w ignores differences related solely to space or tab characters 
and reduces sequences of these characters to a single space. 
This option also removes trailing blanks. When you specify the 
-w option, diff uses additional memory to create a third 
table for each fine in its compressed form. 

Note: The appendix, “diff File-Matching Algorithm,” discusses 
the theory of file matching and how it affects diff. 

To compare the two files, newf ile and oldf ile, you enter the 
following command: 

diff newfile oldfile 

diff compares the two files and gives you a set of instructions to 
follow to change oldfile into newfile. The instructions begin with 
the following message: 

TO TRANSFORM oldfile INTO newfile ... 

The instructions are displayed in three types of blocks : a delete block, 
an append block, and a change block. 

A delete block describes the lines that you should delete from 
oldfile, and it has the following form: 

*** DELETE [J,J] FROM Oldfile *** 

<Text of first line in oldfile. 

<Text of second line in oldfile. 

<Text of third line in oldfile. 

The numbers i and j are the first and last line numbers inoldfileof 
the lines to be deleted. A less than (<) sign preceding a line of text 
indicates that you should delete the line. 
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diff Determines the differences between two files 
(continued) 

An append block describes the lines that you should add to 
oldf ile, and it has the following form: 

*** APPEND AFTER i IN Oldfile *** 

>Text of first line that you should add. 

>Text of second line that you should add. 

>Text of third line that you should add. 

The number i is the line number in oldfile after which the lines 
should be added. A greater than (>) sign preceding a line of text 
indicates that you should add the line. 

Note: The line number i will not be correct if you make other 
changes to the lines in oldfile before line number i. 

A change block lists the lines in oldfile that you should change 
and shows how to change them, diff presents this information as a 
series of lines to delete and a series of lines to add in place of the 
deleted lines. A change block has the following form: 

*** CHANGE [ i, j] IN oldfile TO [m,n] IN newfile *** 

<First line in oldfile that you should change. 

<Second line in oldfile that you should change. 

<Third line in oldfile that you should change. 


>New text (from newfile) for first line in oldfile. 

>New text (from newfile) for second line in oldfile. 

>New text (from newfile) for third line in oldfile. 

The numbers i and j are the first and last line numbers in oldfile of 
the lines to be deleted. The numbers m and n are the first and last line 
numbers in newfile of the lines you need to add to oldfile. 

Examples Suppose you wanted to compare the contents of the files cow and 
lamb. The file lamb contains the following lines: 

Mary had a little lamb. 

Its fleece was white as snow. 

Everywhere that Mary went, 

The lamb was sure to go. 
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diff Determines the differences between two files 
(continued) 

The file cow contains the following lines: 

Mary had a very large cow. 

Its fleece was white as snow, 

Mary had a what? 

Everywhere that Mary went, 

If you entered the command 

diff lamb cow 

this utility would produce the following: 

TO TRANSFORM cow INTO lamb . . . 

*** CHANGE 1 IN cow TO 1 IN lamb *** 
< Mary had a very large cow. 


> Mary had a little lamb. 

*** DELETE 3 FROM COW *** 

< Mary had a what? 

*** APPEND AFTER 4 IN COW *** 

> The lamb was sure to go. 

Error Messages The diff utility may generate the following error messages: 

Can't open file 

indicates that diff cannot open the named file. The file may not 
exist, or it may be protected. 

Diff I/O Error 

indicates an I/O problem. 

Improper -1 specification: nn 

indicates that diff cannot interpret the nn value specified with the 
-1 option as a number. 
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diff Determines the differences between two files 
(continued) 


Internal Error: ... 

indicates an internal error. Please contact the Technical Support 
Division at SAS Institute if you see this error message. The 
Technical Support representative will need the following 
information: 

□ the version of diff you are using 

□ the exact wording of the command line you used 

□ the exact wording of the message you received 

□ the size of the files you were trying to compare. 

Line table overflow 

indicates that one of the two line tables, in which diff stores the 
lines from each file while they are being compared, is too small to 
hold the lines in one of the files. Try increasing the line table size 
with the -1 option. 

Not enough memory for nn lines per file 

indicates that you have used the -1 option to increase the line table 
size, but you do not have enough memory to increase it by the 
amount you specified. 

Out of memory 

indicates that diff is out of memory. Try decreasing the line table 
size with the -1 option if possible. Do not use the -w option. You 
can also try decreasing the size of the I/O buffer by using the -b 
option; however, this action makes diff run slower because more 
disk accesses may be required. If you are using a hard disk, this 
factor may be negligible. 

Too many file names: ... 

indicates that you have made an error on the command line in such 
a way that diff assumes you are attempting to operate on more 
than two files. 

Unrecognized option 

indicates that you specified an option that diff does not recognize. 
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grep Searches for and prints regular expressions 
Synopsis grep [> destination] [options] pattern file . . . 

Description The grep utility searches the files you specify for all the lines that 
contain the specified pattern. For each file in which it finds the 
pattern, grep displays, on the screen, the filename, line number, and 
contents of the line that contains the matching string. The patterns that 
you can specify can be specific or general, and they are sometimes 
referred to as regular expressions. In this book, they are referred to as 
patterns. 

For example, suppose you are working on a long document in a file 
named document . txt. You originally were going to call the 
document a user manual, but you have decided to call it a user’s guide. 
You need to see where you have used the word manual to describe the 
document. You could enter the following command: 

grep manual document.txt 

grep displays all of the lines in the file that contain the word manual. 
These lines could include such phrases as the manual, insert the paper 
manually, or refer to your AmigaDOS manual. 

By using special characters as described under “Specifying the 
Pattern” later in this discussion, you can tell grep exactly what to 
look for so that it does not display lines in which you are not 
interested. 

To specify the files that you want grep to search, you can use the 
AmigaDOS wildcards (#?). For example, to search all files in the 
current directory that have an extension of . c, enter # ? . c as the 
filename. To search all files in the root level directory of drive df 0 : 
that begin with the letter g and have the extension . c, enter 
df 0 : g# ? . c. AmigaDOS ignores the case of filenames. It will find the 
files you specify whether you enter the name in uppercase, lowercase, 
or mixed case. 

You can redirect the output from grep by specifying a greater than 
(>) sign followed by the destination where you want the output sent. 
You may want to redirect the output to a file and print that file. 
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grep Searches for and prints regular expressions 
( continued ) 

grep supports the following options: 

-c prints the total number of matched lines. 

-f prints only the names of all files in which grep finds a string 
that matches the pattern. 

-n tells grep not to display line numbers. 

-p displays only printable ASCII characters. Non-printable 
characters are filtered out. This option is useful if you are 
searching a binary file that may contain control characters. 

-q does not display filenames or line numbers. 

-s displays the names of all files that grep searches. Normally, 
grep displays only those filenames in which it found a match 
for the pattern. 

-v prints only the lines in which a match of the pattern is not 
found. 

-V prints the version number of grep. 

-$ tells grep not to distinguish between upper- and lowercase. For 
example, if you use this option, the pattern int would match 
int, INT, Int, and INt. 

Specifying the By using characters that grep interprets in special ways, you can 

Pattern specify some very complex patterns. Because grep is so flexible, you 
must also be specific about the pattern for which you are searching. 
The following list describes the special characters that you can use to 
specify the pattern for which you are looking: 

is the grep wildcard character. A period will match any single 
character, including a space, tab, newline, or control character. 

A period followed by an asterisk(*) tells grep that any 
number of any characters can be present. The . * sequence is 
equivalent to the # ? sequence for AmigaDOS commands. 

“ ” are used to enclose patterns that include space characters. 
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grep Searches for and prints regular expressions 
( continued ) 


[ ] are used to search for any one character from a set of 

characters by enclosing that set of characters inside square 
brackets. A set of characters enclosed in square brackets is 
called a character class. A character class will match one single 
character. For example, to search for lines that contain vowels, 
you can enter [ aeiou ] . 

- is used to specify a range. Inside a character class, you can 
specify a range of characters by entering the first character 
in the range and the last character in the range separated by 
a hyphen. The first character must occur alphabetically 
before the second. For example, to find any one of the 
lowercase alphabetic characters, you enter [ a-z ] . 

! is used as the negation character when included as the first 
character in a character class. An exclamation point tells 
grep to find any character that is not in the character class. 
For example, to find any one character that is not a 
lowercase alphabetic character, enter [ ! a - z ] . To find any 
one character that is not a lowercase alphabetic character 
and is not the end-of-line character, enter [ ! a-z\N ] . 

* tells grep that the preceding character does not have to be 
present in the pattern but can be present an unlimited number 
of times. In other words, an asterisk means “zero or more 
occurrences of.” 

A period followed by an asterisk tells grep that any number 
of any characters can be present. The . * sequence is equivalent 
to the # ? sequence for AmigaDOS commands. 

+ tells grep that the preceding character must be present in the 
pattern at least one time but can be present an unlimited 
number of times. In other words, a plus sign means “one or 
more occurrences of.” For example, to find all lines in your file 
that contain one or more of the lowercase letter t, enter t+. 

A tells grep that the pattern must begin in column 0. Enter the 
caret ( A ) at the beginning of the pattern, grep will look only for 
those lines in which the pattern occurs beginning in column 0. 
For example, to find all lines that begin with a left parenthesis, 
enter A ( . 

$ tells grep that the pattern must occur at the end of a line. 
Enter the dollar sign at the end of the pattern. For example, to 
find all lines that end with a right parenthesis, enter ) $. 
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grep Searches for and prints regular expressions 
(continued) 

\ is the escape character. If you want to search for any of the 
special characters included in this list, you must enter a 
backslash before that character. For example, to find all lines 
that contain a caret, enter \ ~ . Similarly, if you want to search 
for a backslash, enter two backslashes, \ \ . 

You also need to use the backslash to identify certain 
additional characters. These characters are as follows: 

\b backspace 
\n newline 
\r carriage return 
\s space 
\t tab 

\xij control character identified by hexadecimal digits ij 

For example, to locate all lines containing the Control-g 
character, enter \x0 7. 

You can combine these characters to specify any pattern you need. 
The way in which you specify the pattern to grep determines the 
response you will receive, grep does not convert tabs to spaces or 
change any combinations of spaces and tabs. If grep does not respond 
as you expect it to, try escaping any special characters with the 
backslash (\) character. Alternatively, try reducing the number of the 
special characters in your search pattern. 

Examples To search for one word, you need only specify the word and the file in 
which you want to search. For example, the following command 
searches the file document . txt for the word manual: 

grep manual document.txt 

To search for a string of words that are separated by spaces you 
must enclose the entire string within double quotes, as follows: 


grep "this is the string to search for" document.txt 
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grep Searches for and prints regular expressions 
( continued ) 


Specifying Any Single Character 

You can tell grep that a character can be any character by using a 
period (.) to designate that character. For example, you can specify a 
four-character pattern, beginning with th and ending with n, in which 
the third character can be anything, by specifying the following 
command: 

grep th.n document.txt 

This command will display all lines with patterns such as 
than then thanks Ethan 

The period will match any single character, including an alphabetic 
character, numberic character, space, tab, newline, or control 
character. For example, you can enter the following command: 

grep 123.45 document.txt 

This command will display all lines containing any of the following 
strings: 

1 23a45 123 45 123145 123(45 123.45 

Specifying Character Classes 

A character class is useful when you need to look for characters that 
do not follow a pattern or when you do not care about the case of a 
character. For example, the following command displays all lines 
containing the symbols % , 6 , or ~: 

grep [ — ] document.txt 

If you want to display all lines containing either the or The, you can 
enter the following command: 


grep [Tt]he document.txt 
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{continued.) 

Similarly, you can enter the following command: 
grep [Tt][Hh][Ee] docuraent.txt 

This command displays all lines containing any of the following strings: 
THE THe The the thE tHE tHe ThE 

Using the - $ option produces the same results: 
grep -$ the document.txt 

Inside a character class, you can use a minus (—) sign to specify a 
range of characters. The first character must occur alphabetically 
before the second. For example, the following command displays all 
lines that contain a lowercase letter: 

grep [a-z] document.txt 

Similarly, the following command displays all lines that contain any 
lowercase letter, any uppercase letter, or any decimal number: 

grep [a-zA-ZO-9] document.txt 

A practical use of character classes arises when you need to display all 
the lines in your file in which you refer to a specific year. Since each 
character class matches one character, enter the following command: 

grep [ 0-9 ] [ 0-9 ] [ 0-9 ] [ 0-9 ] document.txt 

If you are concerned only with years in the nineteenth and twentieth 
centuries, then enter this command: 


grep 1 [89 ] [ 0-9] [ 0-9 J document.txt 
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Also, the exclamation point (!) means not if it occurs as the first 
character in a character class. For example, the following command 
displays all lines that contain any character that is not a lowercase 
letter: 

grep [ ! a-z ] document.txt 

The following command displays all lines that contain any character 
that is not the number sign (#): 

grep [ ! # ] document.txt 

Specifying the Number of Times a Character Can Appear 

An asterisk (*) tells grep that the preceding character can be present 
zero or more times. For example, you may have a file in which you 
have referred to Gail and mentioned a year in which some event has 
occurred. To display those lines in which both Gail and a year occur, 
enter the following command: 

grep "Gail. *[ 0-9] [0-9 ]( 0-9) [0-9] " document.txt 

The period (.) followed by an asterisk (*) tells grep that any character 
can be between Gail and the year and that you do not care how many 
of the characters appear. This command would display lines such as 
the following: 

Call Gail Barbara Industries at 1-999-629-9310. 

Gaillard de Marentonneau was a 1900s century botanist. 

My eldest daughter Gail was born in 1969. 

You can also use the asterisk (*) after a character class if you want 
to tell grep that you do not care how many of the characters in the 
character class occur in the pattern. For example, the following 
command displays any combination of zero or more lower- or 
uppercase letters t and the letters he: 


grep [tT]*he document.txt 
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This command displays lines containing strings such as the following: 

he tthe These hero penuche inherit mother 

Using the plus ( + ) sign instead of the asterisk (*) tells grep that you 
want the string to include at least one t. Using a plus sign displays the 
following strings: 

tthe These mother 

If you want to display only lines that contain the word the, you can 
use the following command: 

grep " [tT]+he " document.txt 

Of the previously listed words, this command displays only tthe. If 
you enter an asterisk (*) instead of a plus ( + ) sign, this command 
displays he and tthe. If you include an exclamation point (!) as the 
first character in the character class, this command displays only the 
following strings: 

he hero penuche inherit 

Specifying a Pattern at the Beginning or End of a Line 

As the first character in the pattern, a caret ( A ) tells grep to display 
only those lines that begin with the pattern. For example, to display 
only lines that begin with numerals, you can enter the following 
command: 

grep "[0-9] document.txt 

Similarly, you can tell grep to display only those lines that end with a 
pattern by entering a dollar sign ($) as the last character in the 
pattern. For example, the following command tells grep to display all 
lines that end with the word the: 


grep " [tT]+he$" document.txt 
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Specifying Patterns that Contain Special Characters 

Using a backslash (\), you can search for any of the special characters 
that grep recognizes. For example, if you want to search for a dollar 
sign ($), enter a backslash (\) in front of the dollar sign, grep 
assumes you are looking for a dollar sign and not for a pattern that 
occurs at the end of a line. Similarly, the following command displays 
all lines that contain left brackets ([): 

grep \[ document.txt 

You also can use the backslash (\) to tell grep that you want to 
display all lines that contain backslashes, as follows: 

grep \\ document.txt 

To locate all lines containing tab characters, enter the following 
command: 

grep \t document.txt 

You also can use the backslash (\) inside of a character class. For 
example, to find all lines that begin with a space or a tab character, 
you can enter the following command: 

grep " ~ [ \t]" document.txt 

Because the period (.) is the grep wildcard character, to search for 
the phrase and so on . . ., use the following command: 

grep "and so on document.txt 

You can use \xij to search for control characters. Control characters 
are generally used as printer format instructions in files produced by 
word processors. Identify the character by its hexadecimal number (ij). 
For example, to display all lines that contain Control-g, enter the 
following command: 


grep \x07 document.txt 



226 Chapter 10 


grep Searches for and prints regular expressions 
( continued ) 


To find lines that contain Control-z, enter the following command: 

grep \x1a document.txt 

The dollar sign ($) special character works much like the carat ( A ) 
except that it forces the match to occur only at the end of a line. For 
example, to search for all occurrences of the C language comment 
terminator, */, at the end of a line, enter the following command: 

grep \*/$ document.txt 

The backslash (\) tells grep not to interpret the asterisk (*) in its 
special sense as a closure operator. 

Suppose you have a number of C language source files, each with 
filenames that end with . c, and you need to search these files to find 
all calls of either of the read or fread functions. Enter the following 
command: 

grep "f*read *(" #?.c 

This command prints every line in these files that contains either 
read or fread, followed by 0 or more spaces and a left parenthesis. 

You also can search your files for all function definitions. Assume 
that each function definition begins with the function name and 
parameter list on a separate line. You can use the following command: 

grep " A [ a-zA-Z_ ] + [a-zA-Z0-9_ ]*(" #?.c 

The pattern matches only expressions that begin a line. The 
expression must consist of one or more lowercase letters, uppercase 
letters, or the underscore (_), followed by 0 or more spaces, and then 
a left parenthesis. This command will print lines such as the following: 

getl(s) /* get a line */ 

—read ( ) 

my_read(fp) { fread( fp,x) ; } 

However, this command will not select a line such as 


char *getl(p) 


/* get a line */ 
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You can use grep to help locate mismatching left and right braces 
({ }). To print each line that contains a left or right brace, you can 
enter the following: 

grep [{)] jf?.c 

Error Messages grep may generate the following error messages: 

Bad character class 

indicates that grep is unable to interpret a character class in the 
pattern you have asked it to find. Check to see if you have used any 
special symbols that you did not intend to use. This message also 
can be generated if, in specifying a character class and using the 
minus ( — ) character to indicate a range of characters, the first 
character in the range does not alphabetically precede the second 
(for example, [ d-a ] ). 

Bad pattern 

indicates that grep is unable to interpret the pattern you are 
asking it to find. You may have used a special character in the 
pattern that does not make sense in this context. Check to see if you 
have forgotten to escape a special character. 

Can't find file(s) ... 

indicates that grep is unable to find one or more of the files you 
have asked it to search. The files may not exist, or you may have 
misspelled the filenames. 

Can ' t open . . . 

indicates that grep is unable to open the named file. The file may 
not exist or may be protected. 

Closing ] not found 

indicates that grep believes that you have asked it to search for a 
pattern that contains a character class, but you have omitted the 
right bracket (]) that terminates the character class. If not, you may 
have included a left bracket ([) in the pattern but forgot to use a 
backslash (\) before it. 

Empty character class 

indicates that a character class you have used in your pattern has 
no members, for example [ ]. 
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Improper hex specification 

indicates that you have used the x escape sequence but have not 
followed it with two recognizable hexadecimal digits. 

Incompatible combination of options 

indicates that the options with which you have invoked grep are 
contradictory. 

Internal Error: . . . 

indicates an internal error. Please contact the Technical Support 
Division at SAS Institute if you see this message. The Technical 
Support representative will need the following information: 

□ the version number of grep you are using 

□ the exact wording of the command line you used 

□ the exact wording of the resulting error message. 

Invalid option 

indicates that you have used a command line option that grep does 
not recognize. This message also can be generated if your pattern 
begins with a minus sign (— ) but you have not escaped it or 
enclosed the pattern in double quote marks (“). 

No beginning double quote in pattern 

indicates that grep has detected double quote marks (“) in a 
pattern that did not start with a double quote. You may need a 
backslash (\) before the double quote. 

No file arguments provided 

indicates that grep believes you have specified a pattern but no 
filenames. This message also may be generated if you invoke grep 
with a filename but no pattern. 

No pattern or file arguments given 

indicates that grep cannot find either a pattern or filename on its 
command line. 

Out of space 

indicates that grep has run out of space in constructing its pattern 
representation. Please contact the Technical Support Division at 
SAS Institute if you see this message. 

Pattern ill-formed: no terminating double quote 
indicates that you started the pattern with a double quote (“) but 
failed to terminate it with one. 
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Too few arguments to GREP 

indicates that grep demands at least two arguments on its 
command line: a pattern and at least one filename. 
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Synopsis gst [gst-filename] [options] [symbol-name . . . ] 

Description A Global Symbol Table (GST) is a collection of all the information 

defined in a set of header files and stored in a format that the compiler 
can use easily and quickly. You can use GSTs to reduce significantly 
the processing time required for header files. However, GSTs require 
additional disk space and impose some restrictions on your header 
files. For information on creating and using GSTs, refer to Chapter 4, 
“Using the System Header Files to Access Libraries,” in SAS/C 
Development System Library Reference. 

The gst utility helps you manage GSTs and extract information 
from a GST. With the gst utility, you can 

□ load a GST into memory 

□ unload a GST 

□ list all GSTs currently in memory 

□ extract symbol information from a GST. 

GSTs must be loaded into memory before they can be used. 
Normally, a GST is loaded automatically the first time you issue a 
command that needs the GST. After a GST is loaded, it will remain in 
memory until either the system needs the memory, until you manually 
unload it using the gst utility, or until you tell sc to recreate the 
GST. To load a GST into memory, specify the GST command as 
follows: 

gst gst-filename 

The gst utility loads the GST into memory and then exits. 

Note: You should do this only if you plan to remove the disk 
containing the GST from the drive. 

To display information about a symbol contained in a GST, specify 
the gst command as follows: 

gst gst-filename symbol-name 

Some symbols may occur more than once in the GST. For example, 
a symbol may occur once as a structure tag and again as an identifier. 
The gst utility prints all definitions of the same symbol, 
gst supports the following options: 

list 

lists all GSTs currently in memory. You can use this option to 
determine which GSTs to unload if you need more memory. 
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[nam e=]filename 

specifies a GST file created using the makegst option in the sc 
command. You do not need to specify name= unless you want to 
load a GST that has the same name as a keyword (for example, 
name = symbol). If you use the special name anygst, the gst 
utility uses the first GST on its list, as reported by gst list. 

[ s ymbo 1 = ]symbol-name 

displays the type of symbol name and the filename and line number 
where symbol-name is defined. The type may be one of the 
following: 

tag struct, union, or enum name 
identifier variable or function name 
typedef typedef 
include #include filename 
preprocessor preprocessor macro or #define 

You do not need to specify symbol= unless you want information 
about a symbol that has the same name as a keyword (name, 
unload, and so on). 

unload 

forces a GST to be unloaded from memory. If you also specify 
symbol names on the command line, gst prints all definitions for 
those symbols before it unloads the GST. 
verbose 

prints the full definition of symbol-name. 

Examples To load the GST named project .gst, enter the following command: 
gst project. gst 

The gst utility loads the GST into memory and then exits. 

If the header file intuition/intuition . h is included in 
project. gst, you can display the definition of the Window 
structure as follows: 


gst project. gst Window 
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If project. gst is not already loaded into memory, gst loads 
project. gst. After project. gst is loaded into memory, gst 
queries the GST and displays the following information: 

intuition/intuition. h 904 defines "Window" (struct) 

To display additional information, enter the following command: 

gst verbose project. gst Window 

gst also displays the contents of the Window structure with offsets 
for each member. 

To unload the first GST on the GST list, regardless of its name, 
enter: 

get unload anygst 

Error Messages gst may generate the following error messages: 

No GST file specified 

indicates that you did not specify a GST filename. 

Can't find GST file " filename " 

indicates that gst cannot find the file specified. 

Symbol " symbol-name " not found 

indicates that gst could not find the specified symbol. 

Not enough memory to load GST 

indicates that the GST file could not be loaded due to insufficient 
memory. 
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Synopsis hypergst [gst-filename ] 

Description The hypergst utility enables you to browse the definitions of symbols 
and data structures in GSTs (Global Symbol Tables) that are loaded 
into memory. The hypergst utility works with the AmigaGuide 
hypertext system. For information on using AmigaGuide, see Chapter 
3, “Getting Help,” in SAS/C Development System User’s Guide, 

Volume 1: Introduction, Editor, Compiler. 

To browse the definitions in a GST, the GST must be loaded in 
memory. You can invoke the hypergst utility and load a GST in one 
of the following two ways: 

□ You can enter the hypergst command followed by the name of the 
GST file that you want to browse. 

□ From the Workbench you can click on the Hyper GST icon, then 
hold down the Shift key and double-click on the icon for the GST file 
that you want to browse. 

If the GST that you want to browse is already loaded into memory, 
you can invoke hypergst in one of the following two ways: 

□ You can enter the hypergst command without specifying a GST 
filename. The hypergst utility displays a screen listing the names 
of all GSTs in memory. To select a specific GST, click on the name 
of that GST file. 

□ You can double-click on the HyperGST icon. The hypergst utility 
displays a screen listing the names of all GSTs in memory. To select 
a specific GST, click on the name of that GST file. 

After the GST is loaded, hypergst displays a screen containing 
buttons for the various kinds of symbols defined in the GST. These 
buttons are as follows: 

Data Items 

displays external data items declared in header files in the GST 
such as DOS Base. 

Prototypes 

displays prototypes for functions including system functions and 
functions declared in your own header files. 

Typedef s 

displays custom data types defined with a typedef statement 
either in system header files or in your own header files. 
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Structs/Unions/Enums 

displays structure, union, and enumerated type definitions. 
Preprocessor Symbols 

displays preprocessor macros defined in any header file including 
macros with arguments and simple substitution macros. 

If you click on one of these buttons, hypergst displays an 
alphabetical list of all symbols of that type in the GST. If you click on 
the name of a symbol, hypergst displays a symbol information 
screen for that symbol. This screen may contain other buttons that 
reference header files, structure tags, type definitions, and so on. You 
can click on any of these buttons to display more information about the 
highlighted item. 

Error Message hypergst may generate the following error message: 

No GST files in memory 

indicates that you have not loaded any GST files into memory. For 
example, you see this message if you invoke hypergst 
immediately following a reboot and do not specify any arguments. 
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Synopsis lprof [-t=n] [>prog-output-dest] program [program-options] 

Description The lprof utility generates run-time statistics for a program, lprof 
records the amount of time spent in each routine that is called as your 
program runs. The Is tat utility produces a report using the 
information compiled by lprof. This report will help you identify 
modules that run slowly or inefficiently. In other words, lprof 
profiles your code. Profiling tells you where your code spends most of 
its time. You can use this information to identify areas of your 
program where efficiency can be improved, lprof has these 
advantages over the sprof profiler (described later): 

□ lprof tells you which lines of code within a function required the 
most time. 

□ lprof does not require you to compile your application with special 
compiler options that modify the code. 

□ lprof takes less time to profile your code than does sprof, but 
lprof provides a completely different type of analysis. 

□ lprof can profile link library functions. 

To use lprof with your program, you must compile your program 
with the debug option. If you link your program using the link 
option in the sc command, the linker automatically links your 
program with the addsym option. If you are linking with a separate 
slink command, you must specify the addsym linker option. If you 
do not specify addsym, the lprof utility cannot profile any library 
functions. 

lprof gathers statistics by determining, at regular intervals, what 
instruction your program is executing. The default interval is 33 
milliseconds. You can change this interval by specifying a new interval 
(n) in milliseconds with the -t option as follows: 

lprof -t=n program 

You can redirect your program’s output by specifying a greater than 
(>) sign followed by a destination, program is the name of the 
executable that you want to run. If program is not in the current 
directory, you must specify the full pathname. You can specify options 
for your program. 

After lprof loads your program, it runs the program and gathers 
statistics by examining the current program counter at given intervals, 
lprof writes your program’s statistics to the file named prof . out 
in the current directory. You can use the lstat utility to produce a 
report from those statistics. 
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Examples To gather statistics on a simple program named myprog that does not 
take any arguments, enter the following command: 

lprof myprog 

For a program that normally takes command-line arguments, you 
can add them after the program name, as follows: 

lprof myprog -opt 1 -flag 

If you want to redirect the program’s output to a file named 
outf ile, enter the following command: 

lprof >outfile myprog -opt 1 -flag 

If the program is not in the current directory, you must give the full 
pathname, as follows: 


lprof >outfile C:myprog -opt 1 -flag 
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Synopsis Istat [> destination] [options] program [profile] 

Description The istat utility analyzes the profile statistics file created by lprof . 

lprof runs the program, gathers statistics by examining the current 
program counter at given intervals, and writes this information to the 
file named prof . out in your current directory. Istat analyzes the 
information in this file and displays a report on the screen. 

You can redirect the output from Istat by specifying a greater 
than (>) sign followed by the destination where you want the output 
sent. You may want to redirect the output to a file and print that file. 

The profile is the name of the output file created by lprof. Istat 
first looks in your current directory for the default file produced by 
lprof, prof. out. If this file is not in your current directory, or if 
you have changed its name, you must specify its full pathname as the 
value for profile. 

You must specify the program name, istat uses this name to get 
debugging and symbol information for its report. 

Note: This utility assumes that you have compiled the program 
with the debug compiler option. The debug option allows Istat to 
associate code with a specific line. If you do not compile with the 
debug option, Istat reports statistics based on subroutines only. 

This utility assumes that you have linked the program with the 
addsym linker option. The addsym linker option allows the profiler 
to produce statistics for library functions. If you link your program 
using the link and debug options in the sc command, the linker 
automatically links your program with the addsym option. If you are 
linking with a separate slink command, you must specify the 
addsym linker option. 

Istat supports the following options: 

-z tells Istat to display statistics for all subroutines even if 
they were not encountered in profiling. By default, Istat 
does not report subroutines that it does not encounter. 

-f tells istat to display full statistics for each subroutine, 
indicating the line numbers within a module that it 
encountered. By default, Istat displays only summary 
information about the subroutine. 

-t=n tells Istat to display only those routines that have at least n 
hits. By default, Istat prints all subroutines that it 
encountered even once. 
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If the report produced by Istat shows that a large percentage of 
time is spent in one program module, you may want to 

□ redesign the module 

□ incorporate the module into the calling routines, thus eliminating 
calling overhead 

□ rewrite the routine in assembly language 

□ restructure your program. 

You also may find that most of the work being done involves the 
routine in question, and the percentage of time taken is reasonable. 

Examples These examples assume that you have the file named prof . out in 
your current directory and that prof . out was produced with the 
following command: 

Iprof testprog 

To display the basic statistics about your program, enter the 
command Istat testprog as follows: 

1> Istat testprog 

header size 0x1c, Prof ileHeader 0x1c 
719 run + 158 ready + 77 wait = 954 
75.36755 run, 16 . 562% ready, 8.071% wait 
8.06755 samples (58) out of profile range 

counted = 660, RUN - NonTable 661 


Routine 55 

Total 55 

Offset 

Hits 

59.545555 

59.545555 

1c44c 

393 

8.9394?5 

68.484855 

1c6f a 

59 

3.63645? 

72 . 121255 

1 0d38 

24 

2.272755 

74.393955 

18252 

15 


Label 
getrsc 
f rersc 

alcmem [lines 64-102 in mem.c] 
Most hits-1 . 212155 (8) on line 80 
instal [lines 117-146 in sym.c] 
Most hits-1 . 212155 (8) on line 132 


0 . 1 5 1 555 1 00.000055 1ca18 


1 


CXM22 
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This output indicates that lprof sampled the process in which 
testprog was running 954 times, lprof found that your program 
was running 719 of those times. Your program was ready, but another 
process was running 158 times of those times. Your program was 
waiting on another process, such as I/O, 77 times. 

You can display information about subroutines that lprof did not 
encounter by using the - z option. In this example, using this option 
produces information about the s treat and strnepy routines. 

These routines have 0 hits and account for 0% of the runtime, but now 
appear in the output, as in the following: 

1> Istat -z testprog 

header size 0x1c, Prof ileHeader 0x1c 
719 run + 158 ready + 77 wait = 954 
75.36755 run, 16.562% ready, 8.071% wait 
8.067% samples (58) out of profile range 


counted = 

660, RUN - 

■ NonTable 661 



Routine % 

Total % 

Offset 

Hits 

Label 


59.5455% 

59.5455% 

1c44c 

393 

getrsc 


8.9394% 

68.4848% 

1 c6 f a 

59 

frersc 


3.6364% 

72.1212% 

1 0d38 

24 

alcmem (lines 64-102 in mem.c] 





Most hits-1 .2121% (8) on 

line 80 

2.2727% 

74.3939% 

18252 

15 

instal (lines 117-146 in 

sym.c] 





Most hits-1. 2121% (8) on 

line 13: 

0.0000% 

100.0000% 

1ca60 

0 

streat 


0.0000% 

100.0000% 

1ca78 

0 

strnepy 
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For each routine that has line number information, you can display 
more detailed line number information by specifying the -f option. 
The -f option tells Istat to display the percentage of total runtime 
and number of hits for each line that was executed in that routine, as 
in the following: 


1> Istat -f testprog 

header size 0x1c, Prof ileHeader 0x1c 
719 run + 158 ready + 77 wait = 954 
75.367$ run, 16.562$ ready, 8.071$ wait 
8.067$ samples (58) out of profile range 

counted = 660, RUN - NonTable 661 


Routine $ 

Total $ 

Offset 

Hits 

Label 

59.5455$ 

59.5455$ 

1c44c 

393 

getrsc 

8.9394$ 

68.4848$ 

1c6f a 

59 

frersc 

3.6364$ 

72.1212$ 

10d38 

24 

alcmem [lines 64-102 in mem.c] 


0.3030$ (2) on line 64 
1.0606$ (7) on line 68 
0.7576$ (5) on line 69 
1.2121$ (8) on line 80 
0.3030$ (2) on line 90 


2.2727$ 74.3939$ 18252 15 instal [lines 117-146 in sym.c] 

0.1515$ (1) on line 117 
0.1515$ (1) on line 129 
0.4545$ (3) on line 131 
1.2121$ (8) on line 132 
0.1515$ (1) on line 133 
0.1515$ (1) on line 138 


0.1515$ 100.0000$ 1ca18 1 CXM22 
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For a large program, you may want to limit the amount of 
information produced by Is tat by using the -t option. You can use 
the -t option to set a minimum number of hits that must be recorded 
for a subroutine before that subroutine will be included in the display. 
With this option, the final total percentage may not be 100%. Here is 
an example: 

1> lstat -f -t=2 testprog 

header size 0x1c, Prof ileHeader 0x1c 
719 run + 158 ready + 77 wait = 954 
75.367$ run, 16.562$ ready, 8.071$ wait 
8.067$ samples (58) out of profile range 

counted = 660, RUN - NonTable 661 


Routine $ 

Total $ 

Offset 

Hits 

59.5455$ 

59.5455$ 

1c44c 

393 

8.9394$ 

68.4848$ 

1c6f a 

59 

3.6364$ 

72.1212$ 

1 0d38 

24 


Label 

getrsc 

frersc 

alcmem [lines 64-102 in mem.c] 
0.3030$ (2) on line 64 

1.0606$ (7) on line 68 

0.7576$ (5) on line 69 

1.2121$ (8) on line 80 

0.3030$ (2) on line 90 


2.2727$ 74.3939$ 18252 15 instal [lines 117-146 in sym.c] 

0.1515$ (1) on line 117 
0.1515$ ( 1 ) on line 129 
0.4545$ (3) on line 131 
1.2121$ (8) on line 132 
0.1515$ (1) on line 133 
0. 1515$ ( 1 ) on line 138 


0.3030$ 98.3333$ IcaOO 


2 xcovf 
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mkmk Creates makefiles 
Synopsis mkmk [options] [filename]... 

Description The mkmk utility creates makefiles, mkmk examines the source and 

header files you specify, determines which files depend on which other 
files, and generates a makefile. If you do not specify any filenames, 
mkmk examines all the files in the current directory ending with . c, 

. cxx, . cpp, or . cc. 
mkmk supports the following options: 

target = filename 

specifies the name to use in the makefile for the target executable 
module. If not specified, the root part of the name of the first . c, 

. cxx, . cpp, or . cc file in the file list is used, 
force 

tells mkmk to overwrite an existing makefile. 

If you do not specify force and the makefile being created 
already exists, mkmk appends the characters . 0 0 to the filename 
and tries again. If that file also exists, mkmk appends the characters 
. 0 1 to the filename and tries again, mkmk continues incrementing 
the number until it finds a filename that does not exist, 
makef ile=filename 

tells mkmk to write the makefile to the specified filename. The 
default filename is smakef ile. 

After running mkmk, you can build your project by entering smake 
from the Shell or by double-clicking the Build icon from the 
Workbench. If you add any new files to your project, or if you add or 
delete any #include directives in existing files, you need to add them 
to the generated makefile either by editing the makefile or by 
rerunning mkmk. The source code for mkmk is in the 
sc : extras /mkmk directory. 
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omd 

Synopsis 

Description 


Examples 


Disassembles object modules 

omd [> destination] [-x] object [source] 

The omd (Object Module Disassembler) utility program disassembles an 
object file produced by the SAS/C Compiler and produces a listing 
consisting of assembly language statements (interspersed with the 
original C source code if you specified a source filename). 

omd sends the output to the screen unless you redirect it by entering 
a greater than (>) sign followed by a destination. You may want to 
send the output to a file and then print the file. 

The -x option sets the size of the buffer used to hold the external 
symbol section of the object module. For example, -x2 5 0 establishes a 
buffer that can hold 250 external symbols. The default size is 200. You 
should increase the buffer size only if omd reports that there are too 
many external symbols. 

object is the object filename. You must specify the complete filename, 
including the . o extension. 

source is the source filename. If you specify source, you must specify 
the complete source filename, and the source file should have been 
compiled with the debug compiler option. The debug option allows 
omd to associate source lines with the object code they generated. If 
you did not use the debug option, C source lines will not appear in 
the output produced by omd. 

The following example compiles my prog . c to produce myprog . o, 
which is then disassembled with omd. The disassembled listing is 
redirected to the file named myprog. 1st. 


sc debug=line myprog 

omd >myprog.lst myprog. o myprog. c 
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oml Manages libraries 

Synopsis oml [<cmdfile] [>listfile] [ options ] libhle [command [module 

Description You can use the oml (Object Module Librarian) to manage your 
libraries, oml allows you to: 

□ create library files 

□ list the modules in a library file 

□ delete modules from a library file 

□ replace old modules with new modules. 

A link library is a group of object modules, each of which was 
originally in a separate file and consisted of one or more subroutines. 
Some advantages of using a link library are as follows: 

□ The subroutines in a library can be used by several programs. 

□ When you are linking your program, you specify only the library file 
instead of several individual object modules. 

□ The linker includes only those modules in the library that are 
required by your program. 

Each module within the library is identified by a module name, 
which is placed in the object module by the program (the SAS/C 
Assembler or Compiler) that generates the module. The assembler and 
compiler use the name of the object file. 

If a module does not contain a module name, oml assigns a module 
name of the form $nnn, where nnn is a decimal number. 

A module may define one or more public symbols. A public symbol 
is something in the module that is available to other modules, such as 
global variables or functions. When the linker resolves external 
references for a program, it examines each module in each library you 
specify. It decides which of the modules are required by the program it 
is linking by looking at the module’s list of public symbols. If any of 
the program’s unresolved external references match any of the 
module’s public symbols, that module will be included in the 
executable module. 

When writing the modules for your library, be careful to avoid 
duplicate names for public symbols. If you create a library that defines 
a symbol more than once, oml issues a warning message. If you then 
link with that library without correcting the problem, the linker may 
include the wrong module or give a duplicate symbol error. 

To invoke oml, enter the oml command followed by a library name, 
as follows: 


oml mylib.lib 
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Oml Manages libraries 
(continued) 


oml waits for you to enter commands (and module names, if 
necessary) from the keyboard, oml executes the commands as you 
enter them and displays a list of any duplicate symbol names that it 
finds. After you have entered all your commands, enter a Control- 
backslash (Control-X) to terminate the oml. 

You also can include the commands and module names on the oml 
command line. If you enter commands on the command line, oml 
executes those commands and terminates. For example, the following 
command replaces the module ftoc.o in my lib. lib with the 
version of the same module in your current directory: 

oml mylib.lib r ftoc.o 

oml replaces the module, lists any duplicate symbol names it finds, 
and terminates. 

You also can enter some commands on the command line followed 
by some from the keyboard. If you include an at (@) sign at the end of 
the command line, oml executes the commands you enter on the 
command line and then waits for you to enter additional commands 
from the keyboard. You must enter a Control-\ to terminate oml. For 
example, the following command replaces the module ftoc.o in 
mylib.lib with the version of the same module in your current 
directory and then waits for you to enter additional commands from 
the keyboard: 

oml mylib.lib r ftoc.o a 

You also can enter the commands into a file and tell oml to use that 
file as input. You can tell oml to use that file by either of the following 
methods: 

□ entering a less than (<) sign followed by the filename (<cmdf ile) 

as the second item on the oml command line 

□ entering an at (@) sign followed by the filename (acmdf ile) as the 

last item on the oml command line. 

oml sends its output to the screen unless you redirect it by 
specifying a greater than (>) sign followed by a filename. 
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Oml Manages libraries 
(continued) 


Specifying Commands 

Commands specify the actions to be performed by oml with respect to 
the specified library file. Each command is specified as a single 
character, usually followed by a list of module names or object 
filenames. Separate commands and file and module names with one or 
more spaces. If you specify the r, d, or x command, oml assumes that 
the next item on the command line is a file or module name, so that 
item is not checked to determine if it is another command. If you need 
to enter a file or module name that may appear to oml to be a 
command, specify that file or module name as the first name following 
the command, oml supports the following commands: 

r file file . . . 

replaces the named object files in the library or adds them to the 
library, if they are not already present. Each module should be in a 
separate object file. To replace modules within a library, make sure 
that the module contains a module name and that the filename is 
the same as the module name, 
d module module . . . 

deletes the named modules from the library, oml assigns module 
names to those modules without names; therefore, you may need to 
get a listing of names in the library (using the 1 command) to 
determine the name of the module that you want to delete, 
x module module . . . 

extracts the named modules from the library and creates separate 
files using the same names. You may need to get a listing of names 
in the library (using the 1 command) to determine the correct name 
of the module that you want to extract. If the module name 
contains a pathname, oml attempts to create a file with that name. 
If the module name does not contain a pathname, oml creates the 
file in the current directory unless you specify a different pathname 
with the -o option. You can use an asterisk (*) to specify that you 
want all modules extracted, oml terminates if it cannot extract a 
module. You cannot extract and replace the same module with the 
same oml command line. 

1 

generates a listing of the modules in the library after all other 
commands have been executed. If you also specify the -s option, 
the listing includes the public symbols defined in each module. 
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OITlI Manages libraries 
(continued) 


Q[filename ] 

tells oml to execute the commands that you enter from stdin 
(usually defined as the keyboard) or from the filename, if specified. 

If you include this option it should be the last option on the 
command line. 

If you specify the r or d command, oml creates a temporary file in 
which it builds the new version of the library. After oml builds the 
new version, if it does not detect any errors, it deletes the original 
library file (if it existed) and renames the temporary file. Therefore, the 
original library file is not affected if an error occurs. 


Specifying Options 

oml supports the following options: 

-b tells oml not to issue prompts, including prompts for 
missing information. 

-n strips debugging information from modules before 
adding them to the library. 

-o prefix specifies a prefix for the filenames to be created by the 
x command. If the prefix includes a directory name, 
you must include the forward slash (/) at the end of 
the name. 


-s 

-t pathname 
-v 

-x 


includes, in the listing produced by the 1 command, a 

list of the public symbols defined in the module. 

specifies a path for the temporary library. 

tells oml to display messages as it adds or deletes 

modules to and from the library. 

generates a cross reference for variables and functions 

used in a library. 


oml produces warning messages if either of the following are true: 

□ A module that you want to delete or extract is not in the library. 

□ Any module in the library includes a second definition for a public 
symbol. 
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Omi Manages libraries 
(continued) 

Examples Since a single object file is essentially a library of one module, you can 
use oml to find out what module name is included in the object file, as 
follows: 

oml name.o 1 

To build a new library, you can create a list of the filenames of the 
object modules that you want to include in the library and then create 
the library using the following command: 

oml new. lib r aname.lst 

The following command extracts all of the modules in the library 
cfuncs.lib and creates a file for each module in the directory 
: object/: 

oml -o: object/ cfuncs.lib x * 

Note: This command will succeed only if the module names in the 
library do not contain pathnames. 

The following command deletes the module tr ibe . o from the 
library cf uncs . lib: 

oml cfuncs.lib d tribe. o 

The following command lists the modules and symbols in the library 
test . lib: 

oml -s test. lib 1 

You can save this listing in a file named test. 1st by adding the 
greater than (>) sign followed by the filename: 


oml >test.lst -s test. lib 1 
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SCmsg Searches for and corrects errors and warnings 
Synopsis scmsg [ options ] 

Description The scmsg utility helps you find and fix errors and warnings in your 
code. It acts as a filter between you and the compiler, allowing you to 
invoke the editor of your choice and go to the line causing the error or 
warning quickly and easily. 

You can use scmsg with the editor of your choice, using AREXX as 
a communication medium. AREXX is a standard part of AmigaDOS 2.0 
and can be purchased as a third-party product for use under 
AmigaDOS 1.3. If you do not have AREXX, you still can use scmsg to 
control the se editor provided as part of the SAS/C Development 
System, but you will not be able to program the editor keys to control 
scmsg. 

Under AmigaDOS 2.0 and higher, scmsg uses the System Default 
font that you select with the Preferences Font Editor. Refer to your 
AmigaDOS system documentation for more information about setting 
the System Default font. 

To use scmsg, you must compile your program with the 
errorrexx option. 

You can specify the following options in the scmsg command: 
autoedit 

specifies that you want scmsg to invoke your editor automatically, 
open the source file, and move to the line producing the message. 
The default value is noautoedit, 
c on f ig = filename 

specifies the name of a configuration file. Typically, the 
configuration file contains the command necessary to invoke your 
editor, open a source file, and display the appropriate line. For 
more information about configuration files, see “Using AREXX to 
Invoke Your Editor,” later in this section. 

hidden 

specifies that you do not want scmsg to display the message 
browser window until the compiler returns a message. The default 
value is nohidden. 



250 Chapter 10 


SCmsg Searches for and corrects errors and warnings 
(continued) 


To redisplay the message browser window, you can enter scmsg 
nohidden at the Shell prompt or send the AREXX show 
command to the SC—SCMSG AREXX port. For example, you can 
use the following AREXX script to send the show command: 

/* AREXX script to send the SHOW command */ 

ADDRESS ' SC—SCMSG ' 

'SHOW' 

pubscreen=name 

tells scmsg to open its window on the public screen you specify. 
You can abbreviate this option as screen, 
quit 

terminates scmsg. 
rexxonly 

specifies that scmsg should not open a window. Use this option if 
you intend to query scmsg for the messages from your editor or 
some other program that supports AREXX, and you do not want to 
see the scmsg window. 

Unless you specify hidden or rexxonly, scmsg opens a window 
on the Workbench screen. This window contains the first error or 
warning message from the compilation. As additional messages are 
produced, they are appended to the end of the list. These additional 
messages may be produced in the same or a different source file. 

The current message is always highlighted. You can move from 
message to message by clicking on the message or by using the arrow 
keys. The scroll bar on the right side of the window allows you to 
move around in the list. Double-clicking on a message invokes the 
editor at the file and line number specified in the message. 
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SCmsg Searches for and corrects errors and warnings 
(continued) 


The scmsg window lists all messages in the following format: 

primary: class msgno in secondary line lineno: text 

where: 

primary 

is the C source file being compiled. 
class 

is either Error, Warning, Note, or Info. 
msgno 

is the message number. 
secondary 

is the name of the file in which the error or warning occurred. This 
file may be the same file as the primary file, or it may be a header 
file included by the primary file using the jj include statement. 

lineno 

is the line number in the secondary file. 
text 

is the message text. The message text may specify an alternate file 
for a message. If a message describes a conflict between two 
different places in your code, the alternate file gives the location of 
one of them. The secondary file gives the location of the other. If an 
alternate file is available for the message, the text contains the 
words 

See line num file filename. 


Every time a C source file is compiled, all old messages listing that 
file as the primary file are deleted from the scmsg window. 

The following sections describe the options available from the 
Project and Edit menus on the scmsg screen. Many of these menu 
items have menu accelerator keys that allow you to perform the 
specified action without selecting the menu item. To use a menu 
accelerator key, hold down the right Amiga key (just to the right of the 
spacebar) and press the specified key. 
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SCmsg Searches for and corrects errors and warnings 
( continued ) 


The Project Menu 

The Project menu allows you to control your message session. The 
following list describes each option on the Project menu and, where 
applicable, gives the menu accelerator key equivalent. 

Set Options 

sets scmsg options that specify which editor you want to use and 
any options for that editor. These options are typically saved in the 
file ENV: sc /scmsg. The options available are as follows: 

editcommand 

is the Shell command necessary to start your editor. Use the % f 
sequence to indicate where the filename should be in the 
command. If this option is left blank, scmsg does not attempt to 
invoke your editor, and all the other options are ignored. If this 
option is left blank but a portname is specified, scmsg sends 
AREXX commands to the port, if it exists, 
gotof ile 

specifies the AREXX command template needed to open a file. 
Use the % f sequence to indicate where the filename should be in 
the command. Once the filename has been substituted, this 
command is sent to your editor’s AREXX port when a new file 
needs to be opened. If this option is left blank, scmsg always 
uses the editcommand to invoke your editor each time there is 
an error, 
gotoline 

specifies the AREXX command template needed to go to a 
specific line. Use the % 1 sequence to indicate where the line 
number should be in the command. Once the line number has 
been substituted, this command is sent to your editor’s AREXX 
port when scmsg needs to go to a new line. By default, this 
option is set to LL "%l\n" DM %m, which displays the message 
text in the message line of s e after going to the specific line. If 
you change this value to blanks, scmsg does not attempt to 
move to the correct line number in the file, 
hidden 

specifies that s cms g should not open a window. Use this option 
if you intend to query scmsg for the messages from your editor 
or some other AREXX-supporting program and you do not want 
to see the scmsg window. This option does not take any 
arguments. 
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SCmsg Searches for and corrects errors and warnings 
(continued) 


portname 

specifies the name of your editor’s AREXX port. If this option is 
left blank, but edit command is specified, scmsg assumes that 
your editor does not support AREXX. The scmsg utility issues 
the edit command option but does not attempt to send any 
AREXX commands to your editor, 
wait 

specifies that scmsg should not open a window until one or 
more new compiler messages are available. This option does not 
take any arguments. 

Use 

saves the current options to ENV : sc /scmsg. 

Save 

saves the current options in ENV : sc/ scmsg and 
ENVARC : sc/scmsg. The left, top, width, and height 
options are set to the current window’s values. 

Save As . . . 

allows you to save your current options to a specified filename. You 
will be prompted for the filename. You can use the opts load 
command to load this file from AREXX. 

Restore 

reads the option settings from ENV : sc/scmsg into memory. 
Restore from . . . 

reads the options settings from a specified filename. The scmsg 
utility prompts you to enter the filename. 

Reset to SAS/C defaults 

resets all options to the default values provided by the SAS/C 
Development System. Refer to Chapter 8, “Compiling and Linking 
Your Program,” in SAS/C Development System User’s Guide, 

Volume 1: Introduction, Compiler, Editor. These defaults are suitable 
for use with se. 
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Hide Window 

closes the scmsg window until the compiler produces another 
message. 

To redisplay the message browser window, you can enter scmsg 
nohidden at the Shell prompt or send the AREXX show 
command to the SC—SCMSG AREXX port. For example, you can 
use the following AREXX script to send the show command: 

/* AREXX script to send the SHOW command */ 

ADDRESS ' SC—SCMSG 1 
'SHOW' 


Quit 

terminates scmsg. 

The Build Menu 

You can use the Build menu to terminate any current builds or start 
new builds. The following list describes each option on the Build menu 
and, where applicable, gives the menu accelerator key equivalent. 

Abort Build 

terminates any current builds that are active. You may want to 
select this option if, for example, an error in a common header file 
is producing too many warnings or errors. The menu accelerator 
key for this command is Right-Amiga-A. 

Build Project 

starts a new build. The smake utility is invoked from the directory 
specified in the ENV :sc/projdir environment variable. This 
variable is automatically set for you each time you submit a smake 
command or click on the Build icon from Workbench. If unset, 
the current directory is used. The menu accelerator key for this 
command is Right-Amiga-B. Any build that is currently running is 
aborted before the new build is submitted. 

The Edit Menu 

You can use the Edit menu to perform certain actions on the current 
(highlighted) message. The following list describes each option on the 
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Edit menu and, where applicable, gives the menu accelerator key 
equivalent. 

Go to Error 

invokes the editor on the file and line number that produced the 
message. You can perform the same action by double-clicking on the 
message or by pressing the Return key. 

Go to Alternate 

invokes the editor on the alternate file and line. This option is valid 
for messages that have an alternate file and line number specified in 
the form 

See line num file filename. 

You also can edit the alternate file by holding down either Alt key 
and double-clicking on the message or by holding down either Alt 
key and pressing the Return key. 

Delete Message 

removes the highlighted message from the list. The menu 
accelerator key is Right-Amiga-D. 

Clear 

removes all messages from the list. The menu accelerator key is 
Right-Amiga-C. 

Delete by . . . 

displays a submenu that allows you to delete all messages that meet 
specific criteria. The options on the submenu are as follows: 

Message Number 

deletes all messages with the same message number as the 
current message. The menu accelerator key is Right-Amiga-N. 

File 

deletes all messages produced by the same secondary file, 
regardless of the primary file. The menu accelerator key is Right- 
Amiga-F. 

Compilation 

deletes all messages produced by the same primary file. The 
menu accelerator key is Right-Amiga-P. 
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Using AREXX to When scmsg wants to communicate with your editor, it issues an 
Invoke Your Editor AREXX command based on the templates you provide with the Set 

Options submenu and the information from the highlighted message. It 
uses the template in the appropriate option as a base and performs 
substitutions on it. All templates start with a percent (%) sign. The 
following substitutions are performed: 


Template 

Substitution 

%% 

percent (%) sign 

X# 

message number 

%e 

alternate filename 

%k 

alternate line number 

%m 

message text 

%n 

newline character 

%f 

filename 

%1 

line number 

%c 

class (Error, Warning, Note, or Info) 

%xhh 

hexadecimal character specified by hh 

%r 

carriage return 


scmsg ignores any other sequence of a percent (%) sign followed by 
a character. 

If scmsg finds the AREXX port described in your options file, it 
sends the openfile AREXX sequence provided to the port to tell 
your editor to open the necessary file. 

If scmsg cannot locate the AREXX port described in your options 
file, it attempts to invoke your editor on the appropriate file using the 
specified edit command Shell command. If successful, it goes to the 
appropriate line using the AREXX command template. 
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scmsg 

(continued) 


Using the 
SCSCMSG AREXX 
Port 


Searches for and corrects errors and warnings 


The following values are typical of what might be found in a 
configuration file created for se by the Set Options submenu under the 
Project menu: 


editcoramand 
portname 
gotof ile 
gotoline 


SC:C/SE 

SC_SE 

OW 

LL "%l\n" DM %m 


The edit command is the Shell command that invokes se. The 
portname is the name of the editor’s AREXX port. The gotof ile 
command is the command required to open the specified file, and the 
gotoline command tells scmsg to go to line %1 and display %m. 

Configuration files and example AREXX scripts for several popular 
editors have been included with the SAS/C Development System in 
subdirectories of the scrextras drawer. Check that drawer to see if 
support for your editor has been provided. 

You can also use the built-in AREXX port in scmsg to get information 
on the messages remotely from your editor or from any other program 
that supports AREXX. The port’s name (for use with the AREXX 
address command) is SC_SCMSG. The following commands are 
supported: 

abort 

aborts any builds currently running, 
altf ile 

returns the alternate filename (if any). An empty string indicates 
that there are no messages on the list or that the current message 
has no alternate file, 
altline 

returns the alternate line number (if any). An empty string indicates 
that there are no messages on the list or that the current message 
has no alternate file, 
bottom 

goes to the last message in the list. 
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build options 

calls the smake utility, using the options specified, to rebuild the 
last project built. Any build that is currently running is aborted 
before the new build is submitted, 
class 

returns either Error, Warning, Info, or Note, depending on 
the current message, 
clear 

deletes all messages, 
delcomp [ filename ] 

deletes all messages with the specified filename as their primary 
filename. If no filename is specified, the primary filename of the 
current message is used. If the current message is deleted, the next 
non-deleted message becomes current, 
delete 

deletes the current message and goes to the next message in the list, 
del file [filename] 

deletes all messages with the specified filename as their secondary 
filename. If no filename is specified, the secondary filename of the 
current message is used. If the current message is deleted, the next 
non-deleted message becomes current, 
delnum [msgno] 

deletes all messages with the specified message number. If no 
message number is specified, the number of the current message is 
used. If the current message is deleted, the next non-deleted 
message becomes current, 
file 

returns the filename for the current message. An empty string 
indicates there are no messages on the list, 
number 

returns the error number. An empty string indicates that there are 
no messages on the list. 



Utility Reference 259 


SCITIS9 Searches for and corrects errors and warnings 
(continued) 


hide option 

closes the scmsg window, but keeps scmsg running. By default, 
the scmsg window reappears when a new message is issued from 
the compiler. To change when the window reappears, you can 
specify one of the following options: 

autoedit 

specifies that you want scmsg to invoke your editor 
automatically, open the source file, and move to the line 
producing the message, 
noautoedit 

cancels autoedit mode, 
rexxonly 

specifies that scmsg should not open a window. Use this option 
if you intend to query scmsg for the messages from your editor 
or some other AREXX-supporting program and you do not want 
to see the scmsg window. This option does not take any 
arguments. To cancel rexxonly mode, you must send the 
norexxonly command, 
norexxonly 

cancels rexxonly mode. If you send a norexxonly 
command, then scmsg opens the message browser window 
when it receives the next message. 

You can also send a show command with AREXX or reinvoke 
scmsg from the command line to redisplay the window, 
line 

returns the line number for the current message. An empty string 
indicates there are no messages on the list, 
next 

goes to the next message in the list. Unlike Version 6.0, using the 
next command on the last message in the list does not move you 
back to the top of the list. Use the top command to go to the top of 
the list. 

newbld compunit 

tells scmsg to clear all messages for the specified compilation unit. 
When the compiler begins a new build, it sends a newbld message 
to scmsg. If you have set the autoedit option, newbld also 
forces scmsg to invoke the editor on the next new message. 
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newmsg "compunit" "file" line 0 "" 0 class ermum text 
adds a message to scrasg's message list, where: 

compunit is the compilation unit associated with the message 
(the . c filename). Enclose the unit name in double 
quotes (")• 

file is the filename of the message. Enclose the filename in 
double quotes. 

line is the line number of the message. 

0 " " 0 must appear exactly as shown. 

class is either Error, Warning, Note, or Info. 
ermum is a positive error number. If ermum is zero, no error 
message number will be displayed. 
text is the message text. 

If the message text contains the words 


See line nnn file "filename" 


where nnn is a decimal number, then nnn and filename are 
interpreted as the alternate line number and filename associated 
with the message, 
number 

is a synonym for errnum. 
opts [ option ] 

allows you to load, set, and save scmsg options without leaving 
scmsg. You can specify any of the following: 

load filename 

loads scmsg options from the specified file, 
save filename 

saves options to the specified file. This file can contain any 
option that is valid on the command line or from Set Options in 
the Project menu, 
portname name 

sets the name of the editor’s AREXX port to the specified name, 
screen name 

closes the scmsg window and reopens it on the specified public 
screen. 
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prev 

goes to the previous message in the list. Unlike Version 6.0, using 
the prev command on the first message in the list does not move 
you back to the bottom of the list. Use the bottom command to go 
to the bottom of the list, 
quit 

terminates scmsg. 
rexxonly 

specifies that scmsg should close the message browser window and 
not reopen it unless you specify scmsg nohiddenat the Shell 
prompt or send the AREXX show command to the SC—SCMSG 
AREXX port. Use this command if you intend to query scmsg for 
the messages from your editor or some other AREXX-supporting 
program, and you do not want to see the scmsg window, 
select 

selects the current message for editing. Your editor is invoked and 
moved to the proper file and line number. This command is 
equivalent to pressing the Return key on the current message, 
show [activate] 

pops the scmsg window to the front or redisplays the window if it 
is hidden. If you specify activate, the scmsg window becomes 
the active window, and you can enter keyboard commands to 
scmsg. 
text 

returns the message text. An empty string indicates that there are 
no messages on the list, 
top 

goes to the first message in the list. 
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Examples The following AREXX script, when invoked from se, opens the file 

containing the current message, moves to the appropriate line number, 
and displays the message on the editor message line: 


/* AREXX script to move to next error */ 
address 'SC_SCMSG' /* Set up to talk to scmsg */ 

'delete' /* Delete the current error, move to next */ 


options results 


/* Tell AREXX we want the return values */ 
/* of issued AREXX commands */ 


'file ' 

file = result 
'line ' 

line = result 


/* Get the new filename */ 

/* Get the new line number */ 


'text' /* Get the new message text */ 

text = result 


options 


/* Don't care about results any more */ 


address 'SC_SE' 


/* Now talk to the editor */ 


if file = "" then 

'DM No more errors' /* Display Message "No more errors" */ 
else do 

'OW UC' II file II "Od"x /* Open Window "file" */ 

'LL UC' II line II "Od"x /* Go to line "line" */ 

'DM' I I text /* Display Message "text" */ 

end 
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scompare 

Synopsis 

Description 


Example 


Generates patch files 
scompare [options] oldfile newfile 

You can use the scompare utility to create a patch file, oldfile is the 
name of the old binary file, newfile is the name of the new, updated 
binary file. Applying the patch file generated by scompare to oldfile 
produces a file identical to newfile. You can use the s patch utility to 
apply patches created by scompare. 

scompare supports the following options: 

-i info-filename 

specifies the file containing messages to be displayed whenever the 
patch is applied. 

-n match-number 

specifies the number of bytes that must be identical to be 
considered a match. The default value is 10. 

-o out-filename 

specifies the name of the generated patch file. The default filename 
is oldfile. pch. 

-a 

prints the changes as text in addition to creating the patch file. 

Note: You cannot distribute copies of scompare or any other 
utility, except s patch, that is included in the SAS/C Development 
System. The patch file that you create using scompare and the 
s patch utility are both freely redistributable. 

The following command compares the files prog . v 1 and pr og . v2 
and generates the patch file prog. pch in the current directory: 


scompare prog.vl prog.v2 
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Synopsis scopts [ options ] 

Description The scopts utility allows you to set compiler options for a project by 
clicking on the gadget that corresponds to the option. The options you 
specify are used by the sc command whenever you compile and link 
your files. 

To run scopts, you can double-click on the SCoptions icon, or 
you can enter scopts on the Shell command line, scopts displays 
the SAS/C Compiler Options Index window. This window contains 
buttons that open additional windows. Each of these windows allows 
you to set different compiler options. In all, scopts can display nine 
windows: 

Compiler Options Index 

allows you to do the following: 

□ set certain options such as list, xref, link, and map 

□ specify the name of the final executable module 

□ display additional windows such as the Optimizer Options 
window and the Link Options windows 

□ save your option settings to a file named scoptions in the 
current directory 

□ save your option settings in ENV: sc/scoptions. 

Compiler Options 

contains gadgets for miscellaneous options such as debug, 
shortinteger s, and stringmerge. 

Diagnostic Message Options 

contains gadgets for options, such as ansi, strict, and 
errorrexx, that affect which messages are generated by the 
compiler and linker and how those messages are handled. 

Code Generation Options 

contains gadgets for options, such as data, code, and cpu, that 
affect the code generated by the compiler. 

Listing/Cross-Reference Options 

contains gadgets for options, such as listnarrow, 
error listing, and xref system, that affect the content and 
formatting of any listing or cross-reference files generated. 
Optimizer Options 

contains gadgets for options, such as optpeep, optsize, and 
optalias, that affect the performance of the optimizers. 
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Prototype Generation Options 

contains gadgets for options, such as genprotoexterns, 
genprotoparms, and genprototypedef s, that affect how 
prototypes are generated. 

Linker Options 

contains gadgets for options, such as smallcode, stripdebug, 
and batch, that are passed to the linker when the linker is invoked 
by sc. These options are not used by the compiler. 

Map Options 

contains gadgets for options, such as maphunk, mapxref , and 
mapoverlay, that affect the content of the linker map file. 

For a brief description of an option, move the cursor to the option 
gadget and press the Help key. For a complete description of any 
compiler option, refer to Chapter 8, “Compiling and Linking Your 
Program,” in User’s Guide, Volume 1. 

These windows may contain one or more of the following basic types 
of gadgets: 

cycles appear as raised buttons with a cycle symbol on the left side. 
By clicking on the gadget with the left mouse button, you can 
cycle through the setting available for that option. To reverse 
the direction of the cycle, press the Shift key as you click the 
mouse button. 

actions appear as raised buttons. Selecting the button causes an 
immediate action to occur. For example, selecting the 
Compiler Options . . . gadget displays the Compiler 
Options window. 

strings appear as a raised ridge around a text area. You can enter 
data in the area by clicking within the text area and typing. 
When you have finished typing, press the Return key. Some 
string gadgets accept only numeric input. The screen will 
flash or a beep will sound if you try to type nonnumeric data. 

lists appear as a set of control gadgets (a scroll bar, arrow 

gadgets, a string area, and ADD and del buttons) combined 
with a raised scrolling area. Use the scroll bar and arrow 
gadgets to position the scrolling area on specific items. To 
add new items to the list, select the ADD button, type the new 
item name, and press the Return key. To remove an item 
from the list, click on the item (to copy it to the string area), 
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and select the DEL button. To modify an item, click on the 
item (to copy it), and enter any corrections. 

To specify an option for which the scopts utility does not have a 
gadget, enter the option and any parameters required by the option 
into the SPECIAL gadget. You can enter as many additional options as 
you like. If you use the SPECIAL gadget to specify an option for which 
scopts already has a gadget, the next time you invoke scopts, the 
gadget for that option is selected, and the option is no longer included 
in the SPECIAL gadget. The only options remaining in the SPECIAL 
gadget are those for which scopts does not have a gadget. For 
example, if you enter link into the SPECIAL gadget, the next time 
you invoke scopts, the link gadget is selected, and the SPECIAL 
gadget does not contain the link option. 

Any values you enter into the SPECIAL gadget are processed after 
all other gadgets are processed. Therefore, options you enter into the 
SPECIAL gadget may override other options. 

To specify the name of your final executable module, specify a 
filename in the ProgramName gadget. 

To save your option settings, select one of the following options from 
the Project menu: 

Save to SCOPTIONS 

saves the settings to the file scoptions in the current directory. 
You also can click on the Save button in the SAS/C Compiler 
Options Index window to save the settings in scoptions. 

Save as global defaults (ENV:) 

saves the settings to the file ENV: sc/scoptions. You also can 
click on the Save Default button in the SAS/C Compiler Options 
Index window to save the settings in ENV : . The option settings are 
also saved to envarc : , if it exists. 

Save as . . . 

asks you for the name of the file in which you want to save the 
settings. To use the options saved in a file other than scoptions 
or ENV: sc/scoptions, you can specify the filename using the 
with compiler option in the sc command. The options in the 
with file are read as if they were specified in the sc command at 
the position occupied by the with option. 

To exit scopts without saving any of your changes, click on the 
Cancel button. 
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When you run the sc command, it first looks for an sc opt ions 
file in your current directory. If this file does not exist, the s c 
command looks for the ENV: sc/scoptions file. 

The scoptions file is an ASCII file that contains the list of sc 
options that you specify. You can edit this file with a text editor and 
add any options you want. 

To load a previously saved options file or to reset all options to their 
default values, select one of the following options from the Project 
menu: 

Restore from SCOPTIONS 

reads the contents of the scoptions in the current directory into 
memory. 

Restore from global defaults (ENV:) 

reads the contents of ENV: sc/scoptions into memory. 

Restore from . . . 

asks you for the name of the file from which you want to read 
option settings into memory. 

Reset to SAS/C defaults 

resets all options to the default values provided by the SAS/C 
Development System. Refer to Chapter 8, “Compiling and Linking 
Your Program,” in SAS/C Development System User’s Guide, 

Volume 1: Introduction, Compiler, Editor. 

You also can change option settings by specifying the option on the 
scopts command line. For example, to set the math=standard and 
link options, you can enter the scopts command as follows: 

scopts math=standard link 

If you enter the scopts command followed by option settings, 
scopts does not display any windows, and you cannot choose the file 
into which the options are saved. Specifically, scopts performs the 
following tasks: 

1. Reads the scoptions file in your current directory, if it exists. 
If this file does not exist, scopts reads ENV: sc/scoptions. 

2. Adds or changes the options you specified. 

3. Saves the new option settings in the file scoptions in the 
current directory. 



268 Chapter 10 


scsetup Sets up a new project 
Synopsis sc: scsetup [ options ] [directory] . . . 

Description The scsetup utility sets up a directory that you can use for C 

development. You can run scsetup on existing directories or use it 
to create new directories, scsetup creates an icon for the directory 
and copies into the directory icons for the most commonly used SAS/C 
Development System tools, such as smake and CodeProbe. You can 
add icons for any file extensions or tools that you want scsetup to 
copy in addition to the standard icons. 

Specifically, scsetup performs the following actions: 

1. Creates the directory, if necessary. 

2. Creates an icon file for the directory being set up, if it does not 
already have one. scsetup uses the file 

sc : starter_pro ject . info as a template for directory icons. 

3. Creates icons for the files in the directory, if necessary. Default 
icons are supplied for . c, . cxx, . cpp, . cc, . h, .a, and . sink 
files. These icons are in the sc : icons drawer under the name 
def_c.info, def_cxx . inf o, def_h.info, def_a.info, 
and def_smk .info. You can add any default icons needed for 
other extensions by copying an icon into sc : icons with the 
appropriate name (def_ extension, info). 

4. Creates an icon file for any subdirectories of the directory being 
set up, if they do not already have one. 

5. Creates icons for the files in each subdirectory, if necessary. 

6. Copies the contents of the directory sc : starter_pro ject, if 
present, to the directory being set up (if you do not specify the 
nostarter option). This starter directory contains a Build 
icon, a Debug icon, an Edit icon, a Find icon, and an 
SCoptions icon. You can place any other icons or programs in 
this starter directory that you want copied to directories set up 
with scsetup. 

scsetup will not overwrite any existing files or icons unless you 
specify the force option. 

You can specify the following options in the scsetup command: 
force 

tells scsetup to copy icons and files into the directory whether or 

not they already exist. Use this option if you have a directory 

already set up for previous versions of the SAS/C Development 

System. 
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nostarter 

tells scsetup not to copy the contents of the drawer 
sc : starter_pro ject into the directory being set up. Use this 
option to create icons for files in a directory based on their 
extension when you do not want the SCoptions, Edit, Debug, 
Build, and Find icons copied into the directory. 

You can run scsetup from the Shell or from the Workbench. To 
run scsetup from the Shell, enter the following command: 

sc: scsetup [options] [directory] . . . 

If you do not specify a directory name, scsetup sets up the current 
directory. If you specify a directory that does not exist, scsetup 
creates the directory. 

To run scsetup from the Workbench and create a new project, 
double-click on the SCsetup icon, and type the name of the drawer 
when prompted. 

To run scsetup from the Workbench and set up an existing 
drawer, click on the drawer icon. (Click on the actual drawer icon, not 
the file icons in the drawer.) To select additional drawers, hold down 
the Shift key and click on their icons. After you have selected all the 
drawers, hold down the Shift key and double-click on the SCsetup 
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Description The smake utility is a tool that you can use to maintain projects that 
are composed of many files. A file can be C source code, a data file for 
a graphics or audio, or perhaps a spreadsheet file. For example, you 
may have a project that consists of 50 files, and several programmers 
may be responsible for different files. To manage this project, you need 
to keep track of which files have been changed and which files must be 
compiled before other files (that is, which files are dependent on other 
files). You can use smake to keep track of file dependencies, recompile 
and relink any files that have been updated, and produce new product 
files. 

In other words, smake determines if any of the source files have 
changed since the last version of the product file was generated and, if 
so, generates a new product file. 

To use smake, you create a makefile that identifies dependent files 
and target files and describes the actions required to produce a new 
product. A basic description of these terms follows: 

target file is any file that is created or updated by smake. 

Producing this file may require creating or updating 
several intermediate files. 

dependent file is a file that must be created or updated before a 

target file can be updated. A dependent file can be a 
source code file, header file, or object code file. In 
other words, if a dependent file is changed (for 
example, by editing), then the target file must be 
rebuilt. 


actions are the commands necessary to update each dependent 
and target file. Actions can be calls to the compiler or 
linker or basic housekeeping commands, 
makefile is a file that identifies every dependent file required to 
create the target file and describes every action 
required to update or create the dependent and target 
files. 


Note: You can use the mkmk utility (described earlier in this 
chapter) to generate makefiles. 

When you run smake, it re-creates only the first target file specified in 
the makefile (unless you specify an alternate target as described in 
“Using Alternate Targets,” later in this section) and, if necessary, any 
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dependent files needed to re-create the target file. Specifically, smake 
performs the following actions: 

1. Locates and identifies the target file. By default, smake remakes 
the first target file specified in the makefile. You can specify an 
alternate target as described under “Using Alternate Targets,” 
later in this section. 

2. Ensures that any file on which the target file depends already 
exists and is up to date. To determine when dependent files were 
last modified, smake looks at the time stamp of the file. A file is 
considered current if it has a time stamp later than that of any of 
its dependent files. 

Note: Before using smake, make sure that your system clock 
is accurate, using the date command if appropriate. 

An example of the date command under AmigaDOS follows: 

date 1 2-Aug-92 16:34:57 

You must enter the time using 24-hour clock notation. Enter the 
month as a three-character field. 

3. Re-creates the target file if any of the dependent files have been 
modified more recently than the target file. 

Creating the A makefile has the following basic format: 
makefile 

I This is a comment. 

target-f ilel : dependent-f ilel dependent-f ile2 . . . 
actions 

target-f ile2 : dependent-f ilel dependent-f ile2 .. . 
actions 


You can include comments in a makefile by entering a pound (#) 
sign in the first column, smake will ignore the remainder of that line. 
All target file names must 

□ start in the first column 

□ be followed by a colon (:) 

□ be followed by the name of any dependencies of the target. 
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If there are too many dependent filenames to fit on one line, repeat the 
target name and colon on the next line, and enter the remaining 
dependent filenames. 

Immediately after the target-dependency line are any actions 
required to generate the target. Each of the action lines, if any, must 
be indented a minimum of one tab or space. To continue an action line 
onto additional lines, end each continued line with a backslash (\). You 
can have as many action lines as necessary for each target-dependency 
line. You can call smake from within a makefile. You cannot issue the 
cd (change directory) command from within a makefile. 

For example, suppose you have an executable file named myf ile 
that you created by linking two object files, f i 1 e 1 . o and f i 1 e 2 . o. 
These object files are created by compiling the source files f i 1 e 1 . c 
and f ile2 . c, and each of these source files includes the header 
stdio.h. Figure 10.1 shows the relationships among these files. 


Figure 10.1 

Example File 
Dependencies 


Executable File 

(Primary Target) 


Object Files 

(Dependents of Primary and 
Targets of Source Files) 


Source Files 

(Dependents) 



If any information in stdio.h changes, you would have to 
recompile both source files and relink both object files to produce a 
new executable file. However, you can create a makefile that contains 
all of the information necessary to recompile and relink these files and 
then run smake to recompile and relink as necessary. 
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Your makefile could look like this: 

1 jj Primary target is myfile 

2 myfile: filel.o file2.o 

3 sc debug=line link filel.o file2.o to myfile 

4 

5 filel.o: df 1 : source/f ilel .c myheader .h 

6 sc debug=line df 1 : source/f ilel . c 

7 

8 file2.o: df 1 : source/f ile2 . c myheader .h 

9 sc debug=line df 1 :source/file2.c 

Note: Do not enter line numbers in your makefiles. Line numbers 
are included here for use in the discussion that follows. 

The first line is a comment line. The second line identifies the two 
dependent object files of the target file myfile. That is, it identifies 
the files that must be current before myfile can be generated: 
file 1 . o and f ile2 . o. 

Line three gives the command (action) necessary to produce 
myfile. In this example, the only command necessary to produce 
myfile is a call to the compiler, sc, that includes the link option. 

The fifth line identifies the files required to produce the object file 
f ilel .o. The two files are df 1 : source/f ilel . c and 
myheader . h. Line six gives the command necessary to produce the 
object file: a call to the compiler. Lines eight and nine identify the 
dependent files and actions required to produce f ile2 . o. 

Target-dependency and action lines are the primary components of a 
makefile. However, smake provides many special features that you can 
use to make your makefiles more powerful. These features include 
macros, transformation rules, local input files, fake targets, and more. 
The following sections describe all of the special features you can use 
in your makefile. 
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Using Special Symbols 

You can use special symbols to override some of the default actions of 
smake. These special characters are as follows: 

Normally, when an action generates an error, smake stops 
processing. If you want smake to continue processing when it 
encounters an error caused by a specific action, begin the action 
line with a minus ( — ) sign. If you want smake to continue 
processing after all errors, specify the command line option -k. 
a Normally, smake displays all commands and messages generated 
by those commands on the screen as each command is executed. If 
you do not want a command to be echoed to the screen, begin the 
action line with the at (@) symbol, smake will still display any 
generated messages. If you do not want any commands echoed to 
the screen, specify the command line option -s. 

$ The dollar ($) sign is an escape symbol for the dollar sign itself. In 
other words, to enter a dollar sign in a filename, enter two dollar 
signs ($$). If you enter only one dollar sign, smake thinks that 
the dollar sign indicates the beginning of a macro. 

\ The backslash (\) symbol is an escape symbol for the pound (#) 
sign. Pound signs normally indicate the beginning of a comment. 
To use a pound sign in a command line, enter a backslash before 
the pound sign (\#). 

6 The ampersand (&) symbol is provided for compatibility with other 
implementations of smake. The ampersand is ignored under 
AmigaDOS. 

Using Macros 

You can use macros to represent any character string, including 
AmigaDOS commands, directory specifications, header files, compiler 
or assembler flags, and constant strings. Macros are especially useful 
where long character strings are required. 

Within a makefile, you can define a macro using the equals (=) sign 
as follows: 

macro-name = definition 

Make sure you define a macro before you attempt to use it. If you 
reference a macro that has not yet been defined, that macro will be 
expanded to an empty string. 
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Note: You purposely can define a macro to be the empty string by 
entering only the macro name and the equals (=) sign: 

macro-name = 

To refer to a macro within a makefile, use the following format: 

$( macro-name ) 

For example, you can define the macros source and flags to 
represent the pathname of your source file and the compiler options 
you want to use to compile that file. Using these two macros, our 
earlier example now looks like the following: 

# Define macros for source pathname and compiler options 
SOURCE = dfl: source/ 

FLAGS = debug=line 

# Primary target is myfile 
myfile: filel.o file2.o 

sc $ ( FLAGS ) link $( SOURCE) filel .0 $(SOURCE)file2.o \ 
to $( SOURCE)myf ile 

filel.o: $(S0URCE)f ilel .c myheader.h 
sc $ ( FLAGS ) $(S0URCE)file1 .c 

file2.o: $( SOURCE) file2 . c myheader.h 
sc $( FLAGS) $( SOURCE )file2.c 

Overriding a Macro Definition 

You can override the definition of a macro from the command line of 
smake by specifying the new definition as follows: 

macro-name = new-definition 

If you specify a macro definition on the smake command line, do not 
include spaces around the equals ( = ) sign. For example, you can 
redefine the debug macro as follows: 


smake -f editor debug=yes 
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Using Default Macros 

smake provides five default macros that are defined after a target- 
dependency line is processed and before the next action line is 
processed. 


Macro 

Definition 

$ 3 

target filename 

$? 

list of dependent files, including the full directory pathnames, 
that are not current (that is, they have time stamps later than 
the target time stamps) 

$* 

name of the first dependent file, including the full directory 
pathname but excluding the filename extension 

$< 

name of the dependent file that caused the action, excluding the 
directory pathname but including the filename extension 

$> 

name of the dependent file that caused the action, excluding 
directory pathnames and filename extension 


For example, your makefile could contain the following target- 
dependency line: 

obj/new/test .0: src/new/test.c hdr/test.h 

This line defines the source file as test . c located in the directory 
src/new and the header file test . h located in the directory hdr. If 
the source file test . c has a time stamp later than the target file 
test . o, then the default macros will have the following values: 


Macro 

Value 

$3 

ob j /new/test . o 

$? 

sr c/new/test . c 

$* 

src/new/test 

$< 

test . c 

$> 

test 
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Note: The value of each of these default macros changes after each 
target-dependency line is processed. 

Defining Transformation Rules 

You can use transformation rules with macros to tell smake how to 
make a file with a given filename extension from another file with a 
different filename extension. Transformation rules are most useful 
when you have several files with which you want to perform the same 
action, smake uses transformation rules if you do not specify explicitly 
the action required to create a certain target. 

For example, you can have a transformation rule that tells smake 
how to create object files with extensions of . o from source files with 
extensions of . c. If the only action required to produce the object file 
from the source file is a call to the compiler, your makefile can contain 
the following transformation rule: 


.c.o: 
sc $* 

Then, smake would compile source files (os . c and strbpl . c) 
without an action line for each source file that explicitly specified the 
call to the compiler: 

.c.o: 
sc $* 

obj/os.o: os.c 
obj/strbpl .0: strbpl. c 

Using Fake Targets 

Fake targets are a set of predefined targets that allow you to control 
the behavior of smake. smake does not remake fake targets. Fake 
targets allow you to set logical names, specify actions to be taken for 
certain conditions, and suppress certain messages. 
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smake provides five fake targets: 

.DEFAULT 
. IGNORE 
.ONERROR 
. SET 
.SILENT 

The following list describes these targets in detail 
.DEFAULT 

specifies an individual action or a set of actions to be executed if 

□ there are no actions specified for a given target-dependency line 

□ there is no default transformation rule for the given target- 
dependency pair. 

The command line syntax used for the .DEFAULT target is as 
follows: 

. DEFAULT : 
action-1 
action-2 


action-n 

You can use . default actions to display messages to the screen as 
smake is running. For example, your makefile can consist of the 
following lines: 

.DEFAULT: 

; this target needs remaking $a 
alpha. cpp: alpha. clp 

If alpha .clp has a later time stamp than alpha . cpp, smake 
will print the following message to your screen: 


this target needs remaking alpha. cpp 
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IGNORE 

tells smake to ignore any error caused by the action lines. 
Specifying . IGNORE is equivalent to calling smake with the -i 
option. To specify .IGNORE, include the following line in your 
makefile: 

•IGNORE: 


.ONERROR 

specifies an action or set of actions to be performed when smake 
detects an error. For example, you may want to delete certain 
temporary files or transfer them to a different directory if an error 
occurs. Specify the actions to be taken after the . ONERROR target: 


ONERROR 
action- 1 
action-2 


action-n 


• SET 

allows you to set the values of logical name assignments (as created 
by the assign command) from within a makefile. When the logical 
name is set from within a makefile, the logical name retains 
the specified value and will be in effect for any secondary processes 
spawned from the main process. To specify .SET, use the following 
format: 

.SET: logical-name = value 

The value may be any character, including a space. However, the 
leading and trailing space characters are ignored. 

For example, you can redefine the logical name EXAMPLES as 
follows: 


.SET: EXAMPLES: = df 0 : sc/examples 
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SILENT 

tells smake not to echo the action lines to the standard output 
device before they are executed. Specifying . SILENT is equivalent 
to calling smake with the -s option. To specify . SILENT, include 
the following line in your makefile: 

.SILENT: 


Using Multiple Targets 

If you have several target files that are dependent on the same 
dependent files, you can specify the target files together on the same 
target-dependency line. For example, if prog . c, myf ile . c, and 
newcode.c all included the header file stdio . h, you can use the 
following lines in your makefile: 

prog.c myfile.c newcode.c: stdio. h 

SC $3 

Using Alternate Targets 

Unless you specify an alternate target, smake remakes only the first 
target file specified in the makefile and, if necessary, any dependent 
files needed to re-create the target file. However, your makefile can 
contain target-dependency and actions lines for several targets. To tell 
smake to remake a target other than the first one specified in the 
makefile, enter the name of the target on the smake command line: 

smake target-name 

For example, you can have the following makefile that specifies two 
targets, clean and backup: 

clean: 

delete $(0BJ)files.o.DS 
delete $(0BJ)os.o 
delete $(0BJ)strbpl.o 

backup: 

copy files . c to df 1 : 
copy os.c to df 1 : 
copy strbpl.c to df 1 : 
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If you enter the smake command without specifying a target, smake 
runs the commands listed under clean. To run the commands listed 
under backup, you must use this command line: 

smake backup 

Using Local Input Files 

From within a makefile, you can create a temporary disk file 
containing instructions that is passed to AmigaDOS when you run 
smake. Local input files are useful when you need to enter command 
lines that are too long to fit on one line. 

Any macros defined in the makefile can be used within a local input 
file. Local input files are automatically deleted before smake 
terminates. 

You can construct a local input file with action lines as follows: 

command <[preface] <[!] [(filename)] 
statement 1 
statement2 


statement n 

< 


where: 


command 

preface 


filename 


is the command to be handed to AmigaDOS. 

is any text or symbol to be passed to AmigaDOS before 
the temporary filename. The preface may contain 
spaces. 

tells smake to create a local input file containing the 
statements you specify but not to pass the filename as 
part of the generated command line, 
is the name of the local file. If you do not specify a 
name, smake uses the temporary filename 
temp_smake . tmp. If you specify a filename, enclose 
the filename in parentheses, and do not enter spaces 
before or after the filename. 


statement 1-n are the statements that you want included in the local 
input file. 
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The following example shows a makefile that uses macros and a local 
input file to create the target grep. grep is a utility that is composed ^ 
of C source files and one assembly language module, the startup 
module c . a. 

1 § Generate an updated version of GREP 

2 

3 f) Define macros 

4 SCHDRS = grep.h pat.h 

5 OBJ = obj/ 

6 FLAGS = debug=symbolflush objectname=$ (OBJ) 

7 SC = SC: sc 

8 

9 # Specify file dependencies for GREP executable, generate link 

10 jf command to be passed to AmigaDOS, then specify contents of 

11 # WITH file. 

12 grep: $(0BJ)grep.o $(OBJ)c.o $ (OBJ)_main. o $(OBJ)re_gen.o 

13 grep: $(OBJ)re_match.o $(OBJ)os.o 

14 slink <WITH < ^ 

15 FROM $(OBJ)c.o+$(OBJ)grep.o+$(OBJ)_main.o+$(OBJ)re_gen.o 

16 FROM $(OBJ)re_match.o $(0BJ)os.o 

17 TO grep 

18 LIBRARY LIB : sc . lib+LIB : amiga . lib 

19 < 

20 

21 # Specify remaining file dependencies for file needed to generate 

22 j) GREP executable. 

23 $(OBJ)grep.o: grep.c $(SCHDRS) 

24 $ ( SC ) $ ( FLAGS ) define GREP grep 

25 

26 $(OBJ)c.o: c.a 

27 $ ( SC ) objectname $(OBJ)c.o c.a 

28 

29 $ ( OBJ ) main.o: main.c 

30 $ ( SC ) $ ( FLAGS ) define GREP main 

31 !+ 

32 $(OBJ)re_gen.o: re_gen.c $( SCHDRS) 

33 $ ( SC ) $( FLAGS) define GREP re_gen 

Note: Do not enter line numbers in your makefiles. Line numbers 
are included here for use in the discussion that follows. 
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Lines three through seven define macros. Lines 12 and 13 list the 
files that must be current before smake can remake the grep target. 
If a target has too many dependent files to fit on one line, retype the 
target filename and colon on the next line, and enter the remaining 
dependent filenames. 

Line 14 tells smake to 

1. create a local input file, using the default temporary filename, 
that contains all the lines up to the less than (<) sign in line 19 

2. execute slink to generate the target grep 

3. pass the local input file to slink as a local input file. 

smake generates the following command and passes it to AmigaDOS: 


slink WITH temp_smake . tmp 

The temporary file temp_smake .tmp contains the following lines: 

FROM $(0BJ)c.o $ (OBJ) grep. o $(0BJ)_main.o $(0BJ)re_gen.o 
FROM $(OBJ)re_match.o $(0BJ)os.o 
TO grep 

LIBRARY LIB: sc . lib+LIB : amiga. lib 

Using Default (.def) Default files are makefiles that smake searches whenever your 

Files makefile does not specify what action is required to create a target. To 
determine what action to take to create a target, smake looks for 
instructions in the following order: 

1 . actions specified below the dependency relation in your makefile. 

2. transformation rules in your makefile. 

3. rules taken from the .def file you specify (if any). 

4. rules taken from a file named smake .def in the current 
directory, if it exists. 

5. rules internal to this implementation of smake, as described 
next. 
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Using smake Internal Rules 

The rules internal to smake specify the basic commands for compiling 
and linking a file and the transformation rules for converting assembly 
language, C source code, and header files into object files. These 
internal commands and rules are as follows: 

LD=slink 

AS=asm 

CC=sc 

CFLAGS= 

SCFLAGS= 

.c.O: 

$ ( CC) $ ( SCFLAGS ) $< 

.cxx.o: 

$ ( CC ) $( SCFLAGS) $< 

.cpp.o: 

$ ( CC) $( SCFLAGS) $< 

.cc.o: 

$(CC) $ ( SCFLAGS ) $< 

• a.o: 

$ ( CC ) $( SCFLAGS) $< 

. s .0: 

$ ( CC ) $( SCFLAGS) $< 

.asm.o: 

$ ( CC ) $( SCFLAGS) $< 

Creating and Using Your Own Default File 

You can create your own default files. If you give your makefile a 
name other than smake . def , specify the -b option on the smake 
command line as follows: 

smake -b filename . def 

Your default file must have the file extension .def. 
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Running smake You can run smake from the Workbench or from the Shell. 

To run smake from the Shell, enter the smake command as 
follows: 

smake [ options ] [macro definitions ] [targets] 

To run smake from the Workbench, double-click on the Build icon. 

To specify options from the Shell, simply enter the options in the 
smake command line. To specify options, define macros, or specify 
alternate targets for the Build icon, select the Build icon, choose 
information from the Icons menu, and add the necessary 
parameters in the Tool Types box. 

Whether you invoke smake from the Shell or the Workbench, 
smake looks for the makefile in your current directory. The default 
file names that smake looks for, in the order in which it looks for 
them, are as follows: 

1. smakefile 

2. smakef ile . smk 

3. makefile 

4. lmkfile 

5. lmkfile . lmk 

To use a different makefile name, specify the - f option as described 
below. 

smake supports the following options: 

-a rebuilds all targets and subtargets without regard to time 
stamps. 

-b file uses the .def file you specify instead of the default file 
smake . def. 

-c tells smake to record everything it would have done if it 
had executed the command you entered. When you specify 
the -c option, smake does not execute the command you 
enter. Instead, it creates a batch file containing all the 
instructions it would have executed if you had not specified 
the -c option. This file is named smakefile.bat in the 
current directory, and you can run it by entering the 
following on the command line: 


execute smakefile.bat 
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-d prints detailed debugging information about the processing 
of the makefile. 

-e erases any out-of-date targets before remaking them. 

-f file uses the filename you specify as the input makefile, smake 
attempts to locate the file with the exact name you have 
specified. If this search is unsuccessful, smake searches for 
a file with the name you specified plus an extension of 
.smake. For example, suppose you have an executable 
named alpha and a makefile named alpha . smake in the 
same directory. If you specify smake -f alpha, smake 
will assume that alpha is your makefile. If you receive an 
error message such as Line too long or Unexpected 
punctuation, try renaming your file with an explicit 
.smake extension and running smake with the full 
filename. 

-h prints help information and then exits. 

-i ignores errors caused by executing the actions. Both the -k 
and -i actions should be used with caution because smake 
will continue running. The -k option incorporates all of 
the functionality of the -i option. 

-k ignores error returns from actions passed to AmigaDOS 
and from smake not knowing how to make certain targets. 
Both the -k and -i actions should be used with caution 
because smake will continue running. The -k option 
incorporates all of the functionality of the -i option. 

-n displays the actions smake would have taken, but smake 
does not execute these actions. 

-p prints target descriptions and expanded macros. 

-q determines if the target file is current, smake prints a 1 if 
the target is current or a 0 if it is not. smake will not 
execute any actions. 

-s does not echo actions to the screen before executing them, 
-t touches the target files by updating them with the current 
system time, smake does not execute any of the actions 
associated with these targets. 
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-u rebuilds unconditionally all targets and subtargets without 
regard to time stamps. 

-w forces smake to act as if it was invoked from the 
Workbench. 

-x is for UNIX compatibility. If you specify this option, smake 
attempts to detect any features of the makefile that would 
prevent it from working correctly with the UNIX make 
utility. Examples of such features are: 

□ using a local input file 

□ defining an action line without an initial tab character 

□ specifying multiple target files on a single target- 
dependency line. 

In each case, smake displays a message describing the 
incompatibility. 
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smfind pattern file [file]. . . 

Description The smfind utility helps you find character strings in your source 

code, smfind uses the grep utility to locate the character string you 
specify in the files that you specify, and it displays each occurrence of 
the character string using the message browser (scmsg). You can then 
double-click on one or more occurrences of the character string, and 
scmsg will open the appropriate file at the correct location. 

You can run smfind from the Shell or the Workbench. 

To run smfind from the Shell, enter the smfind command as 
shown above. Enter search patterns as described in the description of 
the grep utility under “Specifying the Pattern.” For the filenames, you 
can enter specific filenames or specify a pattern using the AmigaDOS 
wildcard characters, # ? . 

If smfind finds any matches in the files that you specify, it invokes 
scmsg and sends all occurrences to scmsg. You can then double-click 
on each occurrence to move to that file and line number. 

To run smfind from the Workbench, you need an icon called Find 
in the directory in which you want to search. You can use the 
sc setup utility to copy the Find icon into your project drawer. 
(When you use the scsetup utility on an existing project, it creates 
new icons, but it does not delete or change any existing icons unless 
you specify the force option. For more information, see the 
description of scsetup.) You can also copy the Find icon from 
sc : starter_pro ject to the appropriate directory. 

You can run smf ind from the Workbench in either of the following 
ways: 

□ Click on the Find icon, then hold down the Shift key and click on 
the file or files to be searched. To search only one file, double-click 
on that file. To search more than one file, single-click on each file 
except the last, then double-click on the last file. Remember to hold 
down the Shift key while you click on these icons, smfind displays 
a window asking you to enter a search pattern. Enter search 
patterns as described in the description of the grep utility under 
“Specifying the Pattern.” 

□ Double-click on the Find icon, smfind displays a window asking 
you to enter a search pattern and a file pattern. Enter search 
patterns as described in the description of the grep utility under 
“Specifying the Pattern.” For the filenames, you can enter specific 
filenames or specify a pattern using the AmigaDOS wildcard 
characters, #?. 
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If smfind finds any matches, it invokes scmsg, and sends all 
occurrences to scmsg. You can then double-click on each occurrence 
to move to that file and line number. 

sc : extras/smf ind contains the source code for smfind. 
smfind uses the smcomm interface provided in 
sc : examples /smf ind to communicate with the message browser. 
You can use the smcomm interface to allow any C program to put its 
results in the message browser (as described in the following section). 
The AREXX script sc : examples/smf ind/smcomm. rexx shows 
how to send new messages to scmsg from an AREXX script. 

Using the smcomm smfind uses the smcomm interface to display its results in the 

Interface message browser. You can use the smcomm interface to allow any 
program to put its results in the message browser. 

To use the smcomm interface, you must: 

□ Include the file smcomm. h in your program. This file is in the 
directory sc : examples/smf ind. You can either copy this file to 
your project directory, copy it to the include : directory, or if you 
are using the includedirectory option, add this directory to 
your includedirectory list. Include the file in your program 
using double quotes (“): 

Jf include "smcomm. h" 

Alternatively, you can include this file without copying it by 
specifying the full pathname in the # include statement: 

# include " sc: examples /smf ind/smcomm. h" 

□ Link with sc : examples/smf ind/smcomm. o. The source for this 
file is in sc : examples/smf ind/smcomm. c. 

When your program first starts, it should call ClearSCMSG to clear 
out any old messages that can be cleared: 

int ClearSCMSG( char *compunit); 

ClearSCMSG will not invoke scmsg if scmsg is not already running. 

The parameter compunit is the compilation unit for which you 
want messages cleared. The compilation unit can be any string, and it 
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does not have to be a filename. The compilation unit groups messages 
together so you can clear all messages pertaining to a single 
compilation unit at one time. The smfind utility always specifies a 
compilation unit of SMFIND, which means that the results of the 
previous smfind command are cleared any time smfind is invoked. 
When the compiler compiles a source file, the compilation unit is the 
name of the source file. The compilation unit is always listed in s cms g 
on the far left of the line, before the first colon. The compilation unit 
differs from the file that is displayed when you double-click on a 
message, because the message might have been generated by a file 
included by the original source file. 

When your program decides that it wants to send a message to 
scmsg, your program should call the function AddSCMSG. The 
AddSCMSG function has the following prototype: 

int AddSCMSG(char *compunit, char *file, int line, char *msg); 

The parameters are as follows: 

compunit is the compilation unit associated with the message 
file is the file to which the message pertains 
line is the line number in the file 
msg is the text of the message. 

AddSCMSG automatically invokes scmsg, if necessary. The specified 
message is added as an Info class message, meaning that it is an 
informational message only and is not assigned a message number. If 
you want to modify this, edit the source code to the AddSCMSG 
function in the file sc : examples /smf ind/smcomm. c. The source 
code to AddSCMSG contains comments at the appropriate place to add 
these features. 

If your message text contains the words 
See line nnn file "filename" 

where nnn is a decimal number, then nnn and filename are interpreted 
as the alternate line number and filename associated with the message. 
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Examples The following command searches for the string foobar in all files 
with the . c extension in the current directory: 

smfind foobar #?.c 

The following command searches for both foobar and boobar in all 
files with the . c extension in the current directory: 


smfind [fb]oobar #?.c 
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Synopsis 

Description 


Example 


Applies patches to files 
spatch [options] oldfile 

The spatch utility applies patches to files. A patch file is a binary file 
that describes the differences between an existing file and a new 
version of that file. You can use the s compare utility to generate 
patch files. 

oldfile is the name of the file to be patched, 
spatch supports the following options: 

-o out- filename 

is the name of the generated patched file. If you do not specify the 
-p option, spatch looks for the file oldfile. new in the current 
directory. 

-ppatchfile 

is the name of the patch file generated by the s compare utility. 
The default file is oldfile . pch in the current directory. 

Note: You cannot distribute copies of s compare or any other 
utility, except spatch, that is included in the SAS/C Development 
System. The patch file that you create using s compare and the 
spatch utility are both freely redistributable. 

The following command applies the patch file prog. pch to the file 
prog . v2 in the current directory and places the newly patched file 
into prog. new in the current directory: 


spatch prog.v2 
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Description splat replaces all occurrences of pattern with string in each file that 
you specify, splat does not overwrite the original version of the file 
unless you specify the -o option, splat places the changed file in 
either a temporary file or, if you use the -d option, in the specified 
directory, splat uses the same root filename with an extension of 
. $$$. 

You must use the rules recognized by grep for specifying the 
pattern and string. For example, to specify a string that contains spaces, 
you must enclose the string in double quotes. For additional 
information, see the description of the grep utility earlier in this 
chapter. 

splat supports the following options: 

-d directory 

specifies the directory where you want splat to place the new 
files. Using this option leaves the original versions untouched. If the 
specified directory does not exist, splat attempts to create it. If 
the attempt fails, splat displays an error message. The -o and -d 
options are mutually exclusive. 

-o 

tells splat to overwrite the original version of the file with the 
new version. The -o and -d options are mutually exclusive. 

-s 

displays the name of the file on which splat is currently working. 
It also displays a message saying that no substitutions have been 
performed if it was unable to find the specified pattern in the file. If 
you do not specify -s, splat performs its task silently. 

-v 

displays all lines in which substitutions are made, but it does not 
create new versions of the files. You can use this option to 
determine the changes that splat will make to your files. 

Examples For example, suppose you want to substitute INT for int in every 

declaration of an integer identifier in your C source files. The following 
command replaces int with INT in all files with the . h and . c 
extensions in your current directory. It writes the new versions of 
these files in the directory named /backup. 


splat -d/backup/ int INT jf?.h #?.c 
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However, you do not want calls to printf to become prlNTf. 
Because in these declarations, the string int is followed by a space 
character, you should use the following command instead: 

splat -d/backup/ "int " "INT " jf?.h §?.c 

Similarly, the following command performs the same substitutions, but 
it writes the new versions of the files in the subdirectory backup of 
the current directory: 

splat -dbackup/ "int " "INT " #?.h #?.c 

To avoid errors such as replacing printf with prlNTf, you can use 
the -v option to determine, without changing your source files or 
creating new files, if you have entered the correct command. The 
following command performs the same substitutions as the previous 
command and displays those changes on the screen, but it does not 
change the files: 

splat -v "int " "INT " jj?.h #?.c 

The following command replaces all occurrences of the string 
unsigned char with char within all files with the . c extension in 
the current directory: 

splat "unsigned char" char #?.c 

The following command appends the string -Dxxx to the end of 
each line that contains the string asm in the file smakef ile: 

splat -dbak/ "asm.*$" "6 -Dxxx" smakef ile 

The pattern asm. *$ matches any string beginning with asm followed 
by 0 or more of any character and ending with the end of the line. 

The string £ -Dxxx appends a space followed by -Dxxx to the end of 
the line. 
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You can also use splat to insert lines in a file or to break single 
lines into multiple lines. For example, you can have a file named 
text . c that contains the following line: 

parms(s) ; usage ( ) ; exit ( 1 ) ; 

Suppose you want the calls to usage and exit to be on separate 
lines and indented one tab stop; enter the following command (all on 
one line): 

splat parms(s) ; usage ( ) ;exit( 1 ) ; parms ( s ) ; \n\tusage( ) ; 
\n\texit ( 1 ) ; \n\t text.c 
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Synopsis sprof [report n] [program [ program-options ]] 

Description The sprof utility tells you how much time your program spends 

executing each function and how many times each was called. In other 
words, it profiles your code. Profiling tells you where your code spends 
most of its time. You can use this information to identify areas of your 
program where efficiency can be improved, sprof has these 
advantages over the other SAS/C profiler, lprof : 

□ sprof tells you exactly how much time was spent in each function. 

□ sprof tells you how many times each function was called. 

□ sprof filters out the time spent waiting for the user, if you use the 
appropriate calls to PROFlLE_ON and PROFILE—OFF. These 
macros are described below. 

□ You can use sprof from a library, device, file system, task, the 
Workbench, or any other way of invoking an application on the 
Amiga. 

This utility works under AmigaDOS version 2.0 or later. It does not 
work under AmigaDOS version 1.3. 

The report option tells sprof to produce intermediate reports on 
the status of the program. The parameter n is an integer that specifies 
the number of seconds between reports. You can also get a report at 
any time by sending a Control-F signal to the sprof process. If you 
invoked sprof from the Shell, type Control-F in the Shell in which 
sprof is running. If you invoked sprof from the Workbench, there 
is no easy way to send a Control-F to sprof. 

To use the profiler, you must first compile your program with the 
profile option. The profile compiler option instructs the compiler 
to generate special code at the beginning and end of each function. 

This code notes the time the function was entered and exited and 
passes this information to sprof. 

You can run sprof from either the command line or the 
Workbench. 

To run sprof from the Shell, enter the sprof command as shown 
above. To specify the report option for sprof, specify it in the 
command line before your program name, sprof assumes that any 
options specified after the program name are options to your program. 

To run sprof from the Workbench, click on the profiler icon in the 
s c : c drawer, then hold the Shift key and double-click on the icon for 
the program to be profiled. If you want to specify an sprof option, 
you can add it to the SProf icon as a tool type. You can also add a 
program name as a tool type; however, sprof would always profile 
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that program. Remember, sprof assumes that any options specified 
after the program name are options to your program, not to sprof. 
For a description of how to add tool types to an icon by using the 
Information window, refer to the descriptions of the Information 
option or Information window in Using the System Software 
(Commodore-Amiga, Inc. 1990). 

If you run sprof from the Shell and specify a program name, your 
program is invoked as if you ran it from the Shell. If you run sprof 
from the Workbench and specify a program name (either by double- 
clicking on its icon or by adding it as a tool type to the SProf icon), 
your program is invoked as if you ran it from the Workbench. If you 
run sprof without specifying a program name, sprof initializes and 
waits for a program compiled with the profile compiler option to 
contact it. This mode of operation allows you to profile file systems, 
shared libraries, and devices easily. 

The report format looks like this: 


Name 

Count 

ITime 

ETime 

Pet 

\func.c\fund\26 

10800 

8923 

8923 

49.0 

\func. c:\func2\30 

18 

10867 

1944 

10.7 

\func. c:\func3\40 

1800 

1769 

1769 

9.7 

\func.c\f 100c\47 

1800 

1326 

1326 

7.3 

\main.c\main\10 

1 

18200 

1286 

7.1 

\func.c\myfunc\50 

600 

1886 

560 

3.1 

\main. c:\cleanup\75 

600 

468 

468 

2.6 


18200 100.0 


The columns have the following meanings: 

Name identifies the function in the form \module\function\line, 

where module is the name of the source file, function is the 
name of the function, and line is the line number of the 
beginning of the function. 

Count is the number of times the function has been called. 

ITime is the number of milliseconds spent in the function and its 
subroutines. This number is the total amount of time spent 
over the duration of the program, not just for one call. 

ETime is the number of milliseconds spent in the function body 

itself, not including any time spent in subroutines called by 
the function. 
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Sprof Determines the time a program spends in each function 
(continued) 


Pet is the percentage of the total program time spent in the 
function, not counting subroutines. 

Producing the report causes your program to take longer to run 
(especially if you specify a low number to the report option). 
However, this overhead does not affect the values reported, sprof 
suspends the process being profiled while it generates the reports, so 
the time spent generating reports does not affect the reported times. 
However, if you run other programs at the same time, these other 
programs will affect your results. You should not have other programs 
actively running while you attempt to profile a program. 

You will sometimes find that specific system or library routines are 
using lots of time because they wait for user input or some other 
event. The time spent in these routines is added to the time for the 
function that called them because they were not compiled with the 
profile option. You can prevent the time spent in any section of 
your code from being included in the statistics by including the 
sprof . h file in your program and calling the PROFILE—OFF and 
PROFILE—ON macros. PROFlLE_OFF turns off profiling for the code 
that follows it. PROFlLE_ON reinstates profiling. 

If you compile code that uses PROFlLE_OFF or PROFlLE_ON 
without the profile compiler option, the macros do nothing. They 
do not add code or overhead to your program. 

If you have an executable module that was compiled with the 
profile option, you can still run the module without running 
sprof. If sprof is not running when the program begins executing, 
the program runs without profiling. However, programs compiled with 
profile run slower than programs compiled without profile. 

Within the same application, you can use code compiled with 
profile and code compiled without profile, but any time spent in 
subroutines compiled without profile is credited to the calling 
function. Code compiled without profile never shows up directly in 
s prof's report. 

The various s c link libraries provide profiling autoinitialization and 
autotermination functions that are automatically linked into programs 
that are compiled with the profile option. The sprof 
autoinitialization and autotermination functions run at priority 150. 
Autoinitialization functions and autotermination functions with a 
priority number that is less than 150 will not be included in the 
profile data. For more information about autoinitialization and 
autotermination functions, refer to Chapter 10, “Using Startup 
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sprof Determines the time a program spends in each function 
( continued ) 

Modules, Autoinitialization, and Autotermination Functions,” in SAS/C 
Development System User’s Guide, Volume 1: Introduction, Compiler, 
Editor. 

How sprof Works The profile compiler option tells the compiler to generate code at 
the entry and exit of each function that calls library functions 
—PROLOG and —EPILOG, respectively. The compiler also defines the 
preprocessor symbol —PROFILE. 

—PROLOG and —EPILOG note the time the function was entered and 
exited and pass this information to sprof, which produces a report 
telling you how much time was spent in each function. 

When the —PROLOG and —EPILOG functions are linked into your 
program, autoinitialization and autotermination functions are also 
linked in, which initialize and terminate profiling. If the 
autoinitialization function finds a copy of the sprof utility waiting, the 
function establishes communications with sprof. If sprof is not 
running, the program runs without profiling. 

The compiler never generates profiling code for functions called 
—PROLOG or —EPILOG so as to prevent endless loops in which 
—PROLOG calls itself in its own prolog. 

—PROLOG and —EPILOG are declared as follows: 

jjinclude <sprof.h> 

void — asm -PROLOG (register aO const char *where); 

void asm _EPILOG(register aO const char *where); 

The parameter where is passed in register AO. It points to a character 
string of the following form: 

"\module\function\line" 

where 

module is the name of the file containing the function 
function is the name of the function 

is the line number on which the function begins. 


line 
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Sprof Determines the time a program spends in each function 
(continued) 

For example, if you have a function f oo beginning on line 17 of the 
file f oo . c, the where parameter would be 

"\foo.c\foo\17" 

A NULL where parameter indicates that the PROFILER — ON or 

PROFILER OFF macro has been called. 

PROLOG and —EPILOG were designed for use by the sprof 

utility, but you can replace them with your own code and use them for 
any purpose. If you declare them in your code, make sure you declare 

them with the asm and register aO keywords as shown. If 

you declare either —PROLOG or —EPILOG, you must declare both, 
even if one of them simply returns immediately. 

sc : source/profile . c contains the source code for the SAS/C 
versions of —PROLOG and —EPILOG and the autoinitialization and 
autotermination functions associated with them. 

sc:extras/sprof contains the source code for the sprof utility. 

Examples In the following function, the time spent waiting for a message is not 
included in the statistics, but the statistics will still include the number 
of times the WaitForMsg function is called: 

({include <sprof.h> 

({include <exec/ports .h> 

({include <proto/exec .h> 

void WaitForMsg(struct MsgPort *port) 

{ 

PR0FILE_0FF( ) ; // Turn off profiling 

WaitPort (port) ; // Time spent here doesn't count 

PR0FILE—0N ( ) ; // Turn on profiling 
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Sprof Determines the time a program spends in each function 
( continued ) 


In the following example, the time spent waiting for the user to enter 
input is not included in the statistics: 

({include <sprof.h> 

{{include <stdio.h> 

int GetInputFromUser( void) 

( 

int i; 

printf( "Enter a number between 1 and 10: "); 
do 
( 

PROFILE—OFF ( ) • // Turn off profiling since scanf() 

scanf ( "?5d\n" , Si) // needs to wait for the user 
PROFILE—ON ( ) ; // Turn on profiling again 

if (i < 1 I I i > 10) 

printf("No, a number between 1 and 10: "); 

) 

while( i < 1 II i > 10); 


return i; 
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tb Displays traceback information 

Synopsis tb [>destina£ion] [options] [tbiile [program]] 

Description The tb utility processes the traceback file that is created when you 
link your program with catch. o and your program terminates 
abnormally. 

To get traceback information for your program, you must link your 
program with catch, o. If your program terminates abnormally, 
catch . o creates a standard IFF format file named Snapshot. TB in 
your current directory. This file contains up to six sections: 

□ symbol cross reference 

□ stack 

□ registers 

□ environment 

□ memory 

□ user data. 

Each section contains information about your program at the time it 
terminated. (Two sections, memory and user data, may not be available 
for your program.) 

tb displays the traceback information on the screen unless you 
redirect it by specifying a greater than (>) sign followed by a 
destination. 

If you do not specify any options, tb displays only the current stack 
frame, which indicates the location where the program terminated. By 
specifying options, you can print all of the sections in the traceback 
file. 

By default, tb looks for the traceback file Snapshot. TB in your 
current directory. If you want tb to use a different traceback file, 
specify the traceback file as the tbfile parameter. 

The program parameter specifies the program from which you want 
tb to read debugging information. If you do not specify program, this 
utility uses the program specified in the traceback file. 

Note: Specifying a program is useful when you have two 
executables of your program: one created with debugging information 
and another without debugging information. The version without 
debugging information loads faster, but you still have access to the 
traceback information if your program crashes. 
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tb Displays traceback information 
(i continued ) 

tb supports the following options: 

-1 displays all sections present in the traceback file 
-x displays the location of all symbols encountered in the program 
-s displays the contents of the entire stack at the time your program 
terminated 

-r displays the current contents of registers at the time your 
program terminated 

-v displays the callback chain and the location where the program 
terminated 

-m displays the amount of memory available at the time your 
program terminated (if present in Snapshot. TB) 

-u displays any user data generated by your program (if present in 
Snapshot . TB). 

Examples Suppose you have a program named test it that you link with 

catch, o, and test it terminates abnormally when you run it. You 
can display information about where the program terminates by 
entering the tb command without any options, as follows: 

1> tb 

Program Name: testit; run from CLI 

Program load map (addresses are APTRs, sizes are in bytes) 
220f 78 $1110 211268 $5b4 

Terminated with GURU number 00000005, Divide by Zero Error 
Error occurred at address 221cde = _foo line 5 
called from 22156a = main line 11 
called from 22 1 c6 0 = _main + 704 
called from 2210ca = hunk 0 + $152 

However, the file created by catch, o contains much more 
information. To display all of the information contained in 
Snapshot. TB, you can specify the -1 option, as follows: 

1> tb -1 

TraceDump 1.2 Copyright (c) 1988 The Software Distillery 



304 Chapter 10 


tb Displays traceback information 
(continued) 


TraceDump Utility: catch. o; Version 1, Revision 0 
Processor type: 68000 
VBlankFreq 60, PowerSupFreq 60 

Symbols for hunk 0 

_foo = 22153c _main = 22155c 

Program Name: testit; run from CLI 

Program load map (addresses are APTRs, sizes are in bytes) 

2 2 0 f 78 $1 1 10 21 1268 $5b4 

Terminated with GURU number 00000005, Divide by Zero Error 
Error occurred at address 221cde = _foo line 5 
called from 22156a = main line 11 
called from 22 1 c6 0 = _main + 704 
called from 2210ca = hunk 0 + $152 

Registers: 

D0=00221cde Dl=00000000 D2=00000001 D3=000027 18 
D4=00000001 D5=0000002b D6=0000003b D7=00000000 
A0=0022 1 f 54 A1 =00243f cc A2=0024460a A3=00225c68 
A4=0021 1268 A5=002445be A6=002033c8 A7=002445ae 
PC 221cde C=0 V=0 Z=1 N=0 X=0 


stack top: 244640, stack pointer: 
entire stack, size = $94 bytes 

2445ae, stack length: 

$94 

2445AE 

000003ED 

00221558 

0000002B 

00000000 

. . . m . " . X . . 

. + 

2445BE 

002445CA 

002215 6A 

00225C68 

002445F6 

. $EJ . " . j . " 

h.$E. 

2445CE 

00221C60 

00000001 

00211620 

00225CC4 

' ! 

. ."D 

2445DE 

00226030 

00225C68 

83D10000 

00000021 

. " ' 0 . "h.Q. 

i 

2445EE 

13230021 

00211620 

00244640 

00221 OCA 

. $ F a . " . J 

2445FE 

00244602 

74657374 

6974000A 

00000022 

.$F. testit 


24460E 

60300000 

27100000 

27180000 

00010000 

'0. . ' . . . ' . 


2446 IE 

OO2BOOO0 

003B0022 

60300022 

61300020 

.+. . . ;."'0 

."a0. 

24462E 

24463E 

35300022 

424C0022 

0F740024 

464400FF 

425800FF 

50 . " . t . $FD 
BL." 

. .BX. . 
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Introduction 

The SAS/C Macro Assembler reads an assembly language source file 
and produces an object file in the Amiga object file format. You can 
use the assembler to generate assembly language modules for your C 
programs, or you can generate programs written entirely in assembly 
language. For example, some operations such as directly accessing CPU 
and I/O registers cannot be handled easily in the C language. Also, 
assembly language is sometimes necessary to get the best combination 
of code size and speed. 

The assembler supports the full set of 68xxx mnemonics, an 
extensive set of assembler directives, and a powerful macro facility. To 
use the assembler, you should understand thoroughly the Motorola 
68xxx instruction set. The “Additional Documentation” section in 
“Using This Book” lists books that describe the Motorola 68xxx 
instruction set. If you are writing assembly language modules to be 
called from C functions, or if your assembly language modules call C 
functions, you should also understand the SAS/C function protocol. 
This chapter assumes that you have a knowledge of assembler, but not 
necessarily the SAS/C Macro Assembler. 

This chapter describes the directives supported by the assembler, 
discusses how to write and use macros, and describes how to call C 
functions and assembler modules. 
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Writing Assembly Language Functions 

The following sections provide an overview of the syntax expected by 
the SAS/C Assembler. The topics covered include 

□ the format of assembler statements 

□ the directives supported by the Assembler 

□ how to create and use macros 

□ how to define control sections 

□ how to specify addresses in assembler statements 

□ how to specify floating-point data 

□ the offsets supported by branch instructions. 

Writing Each Motorola 68xxx assembly language source line has the following 
Assembler format: 

Statements 

[label:] operation[.size] operand . . . [ ; comment ] 

You can enter white space (spaces or tabs) before any field. You 
must enter white space between the operation and operand. The fields 
of the source line are described below: 

label 

can start in any column and end with a colon, or can start in 
column one and end with either a colon or white space. A label can 
be up to 31 characters long and can contain letters, digits, 
underscores (_), and dollar ($) signs. A label cannot start with a 
digit, and the case of letters is significant. For example, the 
assembler differentiates between XYZ, xYZ, and XyZ. 

operation 

is the name of an instruction, a directive, or a macro. Do not begin 
an operation in column one. If no label is present, precede the 
operation with white space. If a label is present, you must include a 
colon or white space between the label and operation. The case of 
this field is not significant. For example, MOVE is the same as 
move. 

size 

specifies either the size of the operands or the size of the offset, 
depending on the type of instruction. See the following section, 
“Specifying Sizes,” for additional information. 
operand 

may contain 0 or more expressions, depending on the specific 
operation. Expressions are composed of constants, variables, and 
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operators. The information in the following section, “Specifying 
Expressions,” describes constants and operators in more detail. 

comment 

can be entered in your assembler source code by preceding the 
comment text with a semicolon. 

Specifying Sizes 

Support for size suffixes depends on the instruction that you enter and 
the processor that you use. Check the documentation for your 
processor to determine which size suffixes are valid. For most non- 
floating-point instructions, the following suffixes are valid: 


Suffix Meaning 

none defaults to word (two bytes) 
B byte 

L long (4 bytes) 

S short (same as byte) 

w word (2 bytes) 


For floating-point instructions, the following suffixes are valid: 

Suffix Meaning 

none defaults to word 

B byte 

D double 

L long 

P packed 

S single 

w word 

x extended 



For branch instructions BSR and BRA, the sizes supported by the 
assembler are as follows: 


Suffix Meaning 


none calculates the size offset needed. For externs, the assembler 
generates a 16-bit offset. 

S generates 8-bit offsets. 

B generates 8-bit offsets. 

w generates 16-bit offsets. 

L generates 32-bit offsets, bsr.l is supported only on the 68020 

and higher processors, and you cannot use BSR.L to branch to 
externs. 


For example, the following instruction creates a 32-bit branch: 

BRA. L subpr 

Data are converted into single, double, or extended precision 
according to the type of instruction. For example, the following 
instruction converts the floating-point constant 2.1 into single precision 
and stores it in floating-point register 1: 

fmove.s #2.1,fp1 

As an additional example, the fmove instructions for the floating- 
point constant 2.1 specifying the bit pattern in hexadecimal are as 
follows: 

fmove.s #$40066666 , f p 1 

fmove. d #$4000CCCCCCCCCCCD, f p 1 

fmove. x #$400000008666666666666666, f pi 

Specifying Expressions 

As described earlier, an expression is composed of constants, variables, 
and operators. 

A variable is a label name or a name defined using an assembler 
directive. 
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A constant is a decimal, hexadecimal, octal, or binary number, or an 
ASCII literal. Unless you specify otherwise, the assembler expects a 
decimal number. To specify an ASCII literal, enclose the literal in 
single quotes. To specify a hexadecimal number, precede the number 
with a dollar sign. To specify an octal number, begin the number with 
an at ( @ ) sign. To specify a binary number, begin the number with a 
percent (%) sign. The following table shows how to enter different 
types of constants: 


Type or Base 

Prefix 

Example 

decimal 

none 

1234 

ASCII literal 

’ literal ’ 

’AC9T’ 

hexadecimal 

$ 

$89AB 

octal 

@ 

@743 

binary 

% 

%1011 

floating point 

none 

2.1 

scientific notation 

none 

2.1E + 10 

hexadecimal floating point 

$ 

$4066666 


Note: If you use hexadecimal notation to specify floating-point 
numbers, you must use either the IEEE or FFP bit pattern 
representation. For information about this representation, refer to a 
manual for the 6888x math coprocessor. 

The following table lists the operators recognized by the assembler in 
the order in which they are processed. 


Order 

Operator 

Meaning 

1 

- 

unary minus 


' 

not 

2 

>> 

right shift 


<< 

left shift 


( continued ) 
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Order 

Operator 

Meaning 

3 

4 

multiply 


/ 

divide 


% 

modulus 

4 

+ 

add 


- 

subtract 

5 

< 

less than 


< = 

less than or equal to 


> 

greater than 


> = 

greater than or equal to 


= = 

equal to 


; = 

not equal to 

6 

& 

bitwise AND 


bitwise OR 


For example, in the following expression, PDQ is first negated and 
then multiplied by DEF, and the result is added to ABC: 

ABC+DEF*-PDQ 

Each expression represents a 32-bit value. An absolute expression is 
one that contains only constants. A relocatable expression contains 
symbols whose values are determined during the linking and loading 
procedure. 

Using With the exception of the DC, DCB, and DS directives, an assembler 
Assembler directive is an instruction to the assembler instead of an instruction to 
Directives be translated into object code. Directives cannot begin in the first 
column of the input line. 

The assembler supports the following directives: 

[label] CNOP offset, alignment 

aligns any data structure or entry point to any boundary, alignment 
is the alignment required for the base, such as 4 for long word, and 
offset is the offset from that alignment. 
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CSECT name[ , type[ , align [ , rtype[ , rsize]]]] 

defines section type and alignment requirements. The section 
“Defining Control Sections,” later in this chapter, discusses the 
CSECT macro. 

[label] DC [.size] expression[,expression] . . . 

defines a constant value in memory. 

[label] DCB[.size] n, expression 

defines a constant block in memory. Using the DCB directive is 
equivalent to using the DC directive n times. 

[label] DS [.size] n 

reserves (defines) n memory locations of the size indicated by .size. 
ELSE 

begins an alternative for the IF directive. 

[label] END 

defines the end of the program. 

ENDC 

defines the end of conditional assembly. This directive turns off 
each of the IFxx directives. 

ENDM 

ends a macro definition, 
label EQU expression 

assigns permanently the value of expression to label. 
label EQUR register 

equates an address or data register with label. 

EXITM 

exits the macro expansion. This directive is a synonym for MEXIT. 
FAIL 

generates an error for the next input line. 

FORMAT 

is included for compatibility only. 

IDNT name 

defines a program unit name. 

IF expression 

assembles the following statements to the next ELSE or END IF if 
the expression supplied as its argument is not 0. IF statements may 
be nested. 

IFC string, string 

assembles if the strings are identical. 



IFD symbol 

assembles if the symbol is defined. 

IFEQ expression 

assembles if the expression is 0. 

IFGE expression 

assembles if the expression is greater than or equal to 0. 

IFGT expression 

assembles if the expression is greater than 0. 

IFLE expression 

assembles if the expression is less than or equal to 0. 

IFLT expression 

assembles if the expression is less than 0. 

IFNC string, string 

assembles if the strings are not identical. 

IFND symbol 

assembles if the symbol is not defined. 

IFNE expression 

assembles if the expression is not equal to 0. 

INCLUDE "filename” 

includes external files into the source. You can nest INCLUDE 
directives up to a depth of 3. 

LIST 

tells the assembler to produce a listing file. 

LLEN n 

sets the number of characters per line in the listing file, n can be 
any value from 60 to 132. The default value is 132 characters. 
label MACRO 

begins a macro definition. The following section, “Defining and 
Using Macros,” describes how to define and use macros. 

MASK2 

is included for compatibility only. 

MEXIT 

exits the macro expansion. This directive is a synonym for EXITM. 
NARG 

is the reserved symbol to which the assembler assigns the index of 
the last argument passed to the macro in the parameter list. 
NOFORMAT 

is included for compatibility only. 
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NOLIST 

tells the assembler to stop producing a listing file. 

NOPAGE 

tells the assembler to stop inserting page breaks and title headers in 
the listing file. 

NOOBJ 

stops the production of the object file. 

OFFSET n 

defines offsets. To define a table of offsets using the DS directive, 
you use the OFFSET directive. To end an offset section, use a 
RORG, OFFSET, SECTION, or END directive. 

OPSYN oldname newname 

defines a synonym for opcodes. 

PAGE 

inserts a page break into the listing file. 

PLEN n 

sets the number of lines per page in the listing file, n can be any 
value from 24 to 100. The default is 60 lines. 

label REG Rl[-R2][/R3 [-£4]] . . . 

assigns permanently the register list to label. You can specify 
individual registers by separating each register with a slash 
( R1/R2/R3 ), or you can specify a range of registers by specifying 
the first and last registers separated with a hyphen ( R1-R3 ). You 
can also combine individual registers with a range of registers 
( R1/R3-R5/R7 ). The assembler translates this list into the register 
list mask format used by the MOV EM instruction. 

[label] RORG n 

sets the program counter to n bytes from the start of the current 
relocatable section. 

[label] SECTION name[,type[,CHIP]] 

defines a program section, name is a character string, and type must 
be CODE, data, or BSS. If you specify CHIP, the assembler places 
this section in chip memory. The section “Defining Control 
Sections,” later in this chapter, discusses the SECTION macro. 
label SET expression 

assigns temporarily the value of the expression to the symbol 
identified by label. 

SPC n 

skips n blank lines in the listing file. 
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ttl title 

sets the title string that is printed in the page headers in the listing 
file. The title can be no longer than 40 characters. 

XDEF label[, label] . . . 

defines an internal label as an external entry. By using the XREF 
directive, you can then refer to the symbols generated by these 
labels from other modules and from routines written in the C 
language. 

xref label[, label] . . . 

references an external symbol defined with the XDEF directive. 

Defining and You can define a macro using the following sequence of directives and 
Using Macros instructions: 

label MACRO 


ENDM 

You must begin the definition with a MACRO directive on a line by 
itself. After the MACRO directive, enter the lines that constitute the 
macro procedure. End the macro definition with the endm directive on 
a line by itself. You can use the EXITM directive within the macro 
procedure to exit the macro before the ENDM directive. 

For example, you could define a macro called a copy as follows: 

acopy MACRO 

move.w 4 ( sp ) , \ 1 

move.l 6(sp),\2 
ENDM 

You can invoke this macro with the following statement: 
acopy d0,a5 

The assembler expands the macro as follows: 

move.w 4(sp),d0 
move.l 6(sp),a5 
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Defining Control The SAS/C Macro Assembler does not assume any default control 

Sections sections. You must use either the SECTION or CSECT directive before 
you define any code or data. A SECTION or CSECT directive defines 
the beginning of a relocatable control section. Parameters on these 
directives allow you to name each control section. The assembler uses 
these named control sections to control the location of data and code 
during linking. 

Chapter 12, “How the Compiler Works,” in SAS/C Development 
User’s Guide, Volume 1, describes the sections produced by the 
compiler. 

Using the SECTION Directive 

The SECTION directive follows this format: 

[ZabeZ] SECTION name[ ,type[, CHIP ]\ 

The following list describes each of the parameters. 

name specifies the name of the control section. You can use the name 

MERGED for near data. You can use a specific name only 

once in a given asm file. 

type specifies the type of section. The type can be BSS, DATA, or 
CODE. 

CHIP specifies that this section is to be loaded into chip memory. 

The compiler uses specific names for each section that it produces. 
The linker merges sections that have the same name and type. For 
more information, refer to Chapter 12, “How the Compiler Works,” in 
SAS/C Development System User’s Guide, Volume 1. 

Specifying Addresses with the SECTION Directive 

You can define symbols to be in the data section by using XREF and 
XDEF after the SECTION directive. The following example uses 16-bit 
addressing to reference both code and data: 



SECTION 

MERGED, DATA 


XREF 

xdata 

datal 

DC . W 

10 

data2 

DC.L 

20 


SECTION 

TEXT, CODE 

XREF 

cfunc 



afunc 


XDEF 

afunc 

JSR 

cfunc(PC) 

MOVE.W 

datal (A4) , DO 

MOVE . L 

data2(A4) ,D1 

MOVE . L 

dl , xdata( A4 ) 


To use 32-bit addressing, remove references to the register A4 and to 
the Program Counter (PC). 

Using the CSECT Directive 

Note: The CSECT directive is provided for compatibility with 
previous releases. For new programs, use the SECTION directive 
instead. 

The CSECT directive follows this format: 

CSECT name[ , type[ , a lign[ , rtype[ , rsize]]]] 

The name and type parameters describe the control section being 
defined. The rtype and rsize parameters define how to access the 
information in the section. The align parameter is ignored. The 
following list describes each of the parameters: 

name specifies the name of the control section. You can use the name 

MERGED for near data. You can use a specific name only 

once in a given asm file. 

type specifies the type of the control section. A value of 0 indicates a 
code section, 1 indicates a data section, and 2 indicates an 
uninitialized data section (like the udata section used by the 
compiler). The default value is 0 (code). 
align specifies the alignment requirements of the control section as a 
power of 2. For example, an alignment of 1 means that the 
section will begin on an even address, and a value of 2 means 
that the section will begin at an address divisible by 4. 

Note: This parameter is not used on the Amiga. All sections 
are long-word aligned. 

rtype specifies whether the code or data in the section are addressed 
absolutely, relative to register A4, or relative to the PC. The 
default value is 0 (relative to the PC). The following table 
describes the possible values for rtype. 

rsize specifies the size of the offset for the address. If you specify an 
rsize of 4, the assembler uses absolute addressing. If you 
specify an rsize of 2, the assembler uses the value of rtype to 
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determine how to address code or data in the section. The 
default value is 4. The following table describes the possible 
values for rsize. 

The following table summarizes the valid types and sizes of relocation 
information on the 68000: 


rtype rsize 

0, 1, 2 4 

0 2 

1 2 

2 2 


Description 

32-bit absolute address 
PC-relative address (code section) 
A4-relative address (data section) 
A4-relative address (BSS section) 


Specifying Addresses with the CSECT Directive 

By specifying parameters in the CSECT directive, you can generate 
assembler modules that are compatible with C programs compiled with 
the data=near (base-relative data) and code=near (program 
counter-relative addressing) compiler options. 

You can force address register-relative addressing of data in the BSS 
section by specifying an rtype of 2 and an rsize of 2. Any XREF 
statements for external data elements must appear after the CSECT 
statement, and all data must be addressed relative to register A4. For 
example, the following code moves data around: 



CSECT 

MERGED, 1 , ,2,2 


XREF 

xdata 

datal 

DC . W 

10 

data2 

DC.L 

20 


CSECT 

TEXT, 0 

MOVE . W 

datal (A4) ,D0 

MOVE . L 

data2(A4),D1 

MOVE . L 

dl ,xdata(A4) 



Note: If the XREF statement for the external data precedes the 
CSECT statement, you can use a standard reference to a four-byte 
external address. 

You can force program counter-relative addressing of data in the 
code section by specifying an rtype of 0 and an rsize of 2. The 
XREF statement for the external function must appear after the CSECT 
statement, and the function must be called relative to the program 
counter. For example, the following code calls the function cf unc 


relative to the PC: 


CSECT 

TEXT, 0 , ,0 

XREF 

cfunc 

XDEF 

afunc 

afunc JSR 

cfunc(PC) 

RTS 



Note: If the XREF statement for the external function precedes the 
CSECT statement, you can use a standard JSR instruction to a 4-byte 
external address. 

In addition to specifying addresses relative to address registers and 
to the program counter, you also can specify absolute addresses or 
enter immediate data. The following tables summarize the addressing 
modes supported by the SAS/C Assembler and provide examples of 
each mode. The notation used in these tables is as follows: 


Notation 

Meaning 

An 

an address register (aO— a7) 

bd 

a 32-bit byte displacement 

data 

actual data you want loaded into the register 

Dn 

a data register (dO— d7) 

d 8 

an 8-bit displacement 

d ie 

a 16-bit displacement 

od 

the 32-bit outer displacement 

PC 

program counter 

Xn 

an index register (aO.w — a7.1) 

XXX 

any number in decimal, hexadecimal, octal, or binary format 
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You can specify the displacements, data, and numbers in decimal, 
hexadecimal, octal, or binary format. The information on entering 
operands in the section “Writing Assembler Statements,” earlier in this 
chapter, describes how to specify each type of constant. 

Note: All fields of the operands on the addressing modes marked 
68020 are optional. 

The following table shows examples of register-direct addressing 
modes: 


Mode 

Example 

Dn 

add.w dl ,d0 

An 

addq . w # 1 , a 1 


The following table shows examples of register-indirect addressing 
modes: 


Mode Example 


(An) 

add . 

. w 

( a 1 ) , dO 

(An) + 

add . 

. w 

( a 1 ) + , dO 

-(An) 

add . 

. w 

- ( a 1 ) , dO 

d I6 (An) 

add . 

. w 

1 0 ( a 1 ) , dO 

d 8 (An,Xn) 

add . 

. w 

1 0 ( a 1 , a2 . 1 ) , dO 

bd(An,Xn) 

add . 

. w 

$ 1 0000 ( a 1 , a2 . 1 ) , dO 

([bd,An],Xn,od) 

add , 

. w 

( [ 1 0 , al ] , a2 . 1 , 20 ) ,d0 

([bd,An,Xn],od) 

add . 

. w 

( [ 10, al ,a2. 1 ] ,20) ,d0 


The last three modes are legal only on machines with a 68020 or 
higher processor. 
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The following table shows examples of absolute addressing modes: 

Mode Example 

(xxx).W add.w (100).w,d0 

(xxx).L add . 1 (100).l,d0 

The following table shows how to specify immediate data: 

Mode Example 

fdata add.l #100,d0 

The following table shows examples of program counter-relative 
addressing modes: 

Mode Example 

d 16 (PC) add.w 

d 8 (PC,Xn) add.w 

bd(PC,Xn) add.w 

([bd,PC],Xn,od) add.w 

(fbd,PC,Xn],od) add.w 


1 0 ( PC ) ,d0 
1 0 ( PC , a2 . 1 ) , dO 


$ 1 0000 ( PC , a2 . 1 ) 

(68020 or 
above) 

( [ 10, PC] , a2 . 1 , 20 ) 

, dO (68020 or 
above) 

( [ 1 0 , PC , a2 . 1 ] ,20) 

, dO (68020 or 
above) 


Communicating between Assembly 
Language and C Language 

The following sections describe how to call assembler functions from C 
functions and how to call C functions from assembler modules. 

Calling Assembler modules may be called from C functions in three ways: 

Assembler 
Functions from 
C Functions 



Using Assembly Language with C Language 323 


□ passing parameters by placing them on the stack. Unless you specify 

the parameters=register option or use the asm keyword, C 

functions pass parameters on the stack. 

□ compiling your program with the parameters=register option. 
This option tells the compiler to pass parameters in registers, but it 
allows the compiler to determine which registers to use. 

□ using the asm keyword and specifying which registers the 

parameters are placed in. 

Passing parameters in registers produces a faster, smaller executable 
module. 

Passing Parameters on the Stack 

As previously stated, C functions pass parameters on the stack if you 

do not specify the parameters=register option or use the asm 

keyword. 

For example, the following assembler module, f unc, adds or 
subtracts an integer argument and a double argument depending on 
whether a plus ( + ) sign or a minus (— ) sign is passed in the 
character argument. 


; NOTE 

This 

code assumes that you 

have a math co-processor 


If you do not, your machine will crash when you run 


this 

program. 



xdef 

_func 



section 

code 


_func: 





fmove .d 

8(a7),fp0 ; 

middle 


cmpi .b 

r + \7(a7) 

should I add? 


bne.b 

noadd ; 

no, check subtract 


fadd.l 

16(a7),fp0 ; 

add 'mrright' to 'middle 


bra.b 

exitpoint ; 

ready to return 

noadd: 





cmpi.b 

F-\7(a7) ; 

should I subtract? 


bne.b 

nosub ; 

no, exit with error 


fsub. 1 

16(a7),fp0 ; 

subtract 'mrright' 


bra.b 

exitpoint 

from 'middle' 



nosub: 


fraove.b i-1,fp0 


; return -1 for error 


exitpoint : 

fmove.l fpO,dO ; return 'int' in dO 

rts 

end 

The func assembler module returns an integer. 

To call an assembler module from your C program, include the 
prototype for the assembler module in your C source file before calling 
the function. The prototype for the previous example is the following: 

int func (char lefty, double middle, int mrright); 

For example, you can write the following program to call the func 
module: 

finclude <stdio.h> 

int func(char lefty, double middle, int mrright); 

void main(void) 

{ 

char lefty; 
double middle; 
int mrright; 

lefty = ' + ' ; 
middle = 12345.; 
mrright = 99; 

printf ( "func( + ) = ?Sd\n", func( lefty, middle, mrright)); 

) 


If you save the assembler module func in a file named testa . a and 
if you save the C source code in a file named test . c, you can 
assemble testa . a, compile test . c, and link the resulting object 
modules by entering the following command: 


sc math=6888 1 cpu=68020 link test.c testa. a 
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sc stores the executable module in the file test. The test program 
will pass parameters on the stack. When you run test, you should 
see the following output: 

func( + ) = 12444 

To use the parameters inside your assembler module, you must 
retrieve the parameters from the stack. The arguments are placed on 
the stack from right to left; that is, the leftmost argument is 
immediately above the 4-byte return address in the stack. For example, 
in the following function call, the compiler generates code to push the 
arguments mrright, middle, and then lefty onto the stack. 

char lefty; 

double middle; 

int mrright; 

func( lefty, middle, mrright) ; 

Next, the f unc module is called, and the return address is pushed 
onto the stack. Figure 11.1 shows the stack after the func module has 
been called. 


Figure 11.1 

The Stack after the 
func Module Is 
Called 


Bottom of Stack 


High 

Memory 


Low 

Memory 


mrright 


middle 


lefty 


return address 


work area 
of size n 




Top of Stack 



The arguments mrright, middle, and lefty use 4 bytes, 8 
bytes, and 4 bytes, respectively.* Register A 7 is the stack pointer, and 
it points to the 4-byte return address. 

Note: If you specify the shortintegers option, integers will be 
2 bytes instead of 4. 

Before retrieving arguments from the stack into non-scratch 
registers, you must first save the contents of those registers, so they 
may be restored when your function terminates. Scratch registers are 
registers DO, Dl, AO, Al, FPO, and FP1. 

The following list describes the steps your assembler module should 
take to save register values and establish frame pointers. In these 
steps, n refers to the size of your work area in bytes. 

1. Enter the SUBI instruction if you need local storage: 

SUBI n,A7 

2. Save registers D2 through D7 and A2 through A6 if they will be 
changed during execution of the module. 

3. Save floating-point registers FP2 through FP7 if a 68881 math 
coprocessor is present and if they will be used by the module. 

You can address the arguments from A7 as follows: 


Location 
(A7)+n 
(A7)+4+n 
(A7) + 8+n 
(A7) + 16+n 


Size Contents 

4 return address 

4 argument lefty 

8 argument middle 

4 argument mrright 


Using the parameters = register Option 

Using the parameters = register option tells the compiler to pass 
some of the function arguments in registers instead of on the stack. 
Specifically, the first two pointer arguments are in AO and Al, and the 
first two integral arguments are in DO and Dl. All other arguments 
are passed on the stack. 


The smallest item that can be pushed onto the stack is the size of an integer. The 
size depends on whether you specify the short int compiler option. A char will 
be promoted to an int . 
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The compiler identifies functions that expect arguments in registers 
by placing an @ in front of the function name. The @ replaces the 
underscore (_) that the compiler normally places at the beginning of 
function names. 

Using the parameters = register option is similar to passing 
parameters using the stack. For example, make sure you: 

□ include a prototype of your assembler module in your C source 
program. 

□ retrieve any parameters that are passed on the stack before using 
them. 

□ use the same asm command to assemble your assembler code. 

□ use the same slink command to link your C code. 

However, you must specify the parameters = regis ter option in 
the sc command as follows: 

sc parameters=register test 

Using the asm Keyword 

Using the asm keyword on a function prototype or definition tells 

the compiler to pass parameters in specific registers. 

When you use asm, the calling C function places the parameters 

in the registers required by the assembler module, so no stack 
manipulation inside the assembler module is necessary. 

The following assembler code is the same f unc module that is 
described previously in the section “Passing Parameters on the Stack,” 
but it is modified to use the asm keyword. 

; NOTE: This code assumes that you have a math co-processor. 

; If you do not, your machine will crash when you run 

; this program. 


xdef 

_func 


section 

code 


cmpi .b 

r + ' ,d0 

; should I add? 

bne.b 

noadd 

; no, check subtract 

fadd.l 

dl , fpO 

; add 'mrright' to 'middle 

bra.b 

exitpoint 

; ready to return 



noadd: 


cmpi.b 

,d0 

; should I 

subtract? 

bne.b 

nosub 

; no, exit 

with error 

f sub. 1 

dl , fpO 

; subtract 

'mrright' from 

bra.b 

exitpoint 



nosub: 




fmove.b 

#-1,fp0 

; return - 

1 for error 

exitpoint : 




fmove . 1 

f pO , dO 

; return ' 

int' in dO 


rts 


'middle ' 


end 

To use the asm keyword, you must modify the prototype of the 

assembler module in your C source file. For each parameter that you 
want to pass in a register, precede the parameter with the register 

keyword, two underscores ( .), and the register into which you want 

the parameter to be placed. 

The prototype for the previous example is the following: 

int asm func(register — dO char lefty, 

register fpO double middle, 

register — dl int mrright); 

The lefty argument is placed into register dO, the middle argument 
is placed into register fpO, and the mrright argument is placed into 
register dl. 

The remainder of your C program is the same as that shown earlier 
in the section “Passing Parameters on the Stack.” You also use the 
same s c command as shown in the section “Passing Parameters on the 
Stack.” 

When you are declaring the C+ + functions with the asm 

keyword, make sure that you do not use registers reserved for special 
parameters. The following list describes special considerations for 
declaring asm functions in your C+ + source files. 

□ If you are using C+ + member functions as asm functions, 

register AO will be used to point to the this pointer for these 
functions. You cannot use register AO for your own parameters. In 
your source file, declare the member functions with the a sm 
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register keyword, but do not specify register aOfor any of 

the parameters. 

□ If you are using C+ + constructors or destructors as asm 

functions, register DO will be used to point to a hidden C+ + 
parameter. You cannot use register DO for your own parameters. 
Since constructors and destructors are member functions, you 
cannot use register AO either. 

In your source file, declare the constructors and destructors with 

the asm register keyword, but do not specify register aO 

or register dO for any of the parameters. 

□ If you define a function that returns a class for which you have 
defined a copy constructor, and you are using the function as an 

asm function, register A1 will be used to point to the area of 

storage used for the return value for the copy constructor. You 
cannot use register A1 for your own parameters. 

In your source file, declare the function with the asm register 

keyword, but do not specify register al for any of the 

parameters. 

Returning Values to the Calling Function 

Your assembler module should return values in one or more registers. 
The register(s) depend on the data type of the prototype for your 
assembler function as declared in the calling C file. Function return 
values are passed back in one or more registers, depending on the 
return type declared for the function. The conventions are as follows: 


Return Length 


Type 

(Bits) 

Syntax 

Meaning 

char 

8 

DO . B 

low byte of DO 

short 

16 

DO .W 

low word of DO 

long 

32 

DO .L 

all of DO 

pointer 

32 

DO .L 

all of DO 

float 

32 

DO . L 

all of DO 

float (68881) 

32 

FPO . S 

single precision in FPO 

double (IEEE) 

64 

DO .L,D1 .L 

high bits in DO 

double (FFP) 

32 

DO .L 

all of DO 

double (68881) 

96 

FPO .X 

all of FPO 
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When calling a function that returns a structure or union, the 
compiler pushes the location of a buffer before the first parameter. If 
the assembler module returns a structure or union, it must copy the 
structure or union to the memory pointed to by this value. 

After setting up the return value, the assembler module exits by 
reversing the steps described earlier: 

1. restore registers that were saved. 

2. advance the stack pointer in register A7 past the work area. 

3. return to the caller using an RTS instruction. 

The calling function pops the arguments from the stack. 

Calling C The steps you take to call a C function from an assembler program 
Functions from vary, depending on whether or not you compile your C function using 
Assembler the parameters = register option. 

Functions If the C function returns a structure or union, the assembler 

function must reserve space for the structure or union and push the 
address of the buffer before the first parameter. 

If you are not using registerized parameters, follow these steps: 

1. If the function returns a structure or union, push a 4-byte pointer 
to a work area into which the return value can be copied. 

2. Push the arguments on the stack in the same order in which they 
are listed in the function’s prototype. 

3. Call the function using the JSR instruction. 

4. After control returns from the called function, adjust the stack 
pointer to account for pushed arguments. 

For example, the following code calls the function cfunc with two 
parameters that are currently in registers D7 and D6 and stores the 
return code in the ret variable. 


XREF 

cfunc 


MOVE . L 

D7,-(A7) 

;push argument 

MOVE . L 

D6,-(A7) 


JSR 

cfunc 

;call function 

ADDQ 

18, A7 

jrestore stack ptr 

MOVE . L 

DO, ret 

;save return value 


If you are using registerized parameters, follow these steps: 

1. If the function returns a structure or union, push a 4-byte pointer 
to a work area into which the return value can be copied. 

2. Place the appropriate arguments in the correct registers. 
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Referencing 
Global Data 


3. Push any remaining arguments onto the stack. 

4. Add an @ to the front of the function name, and call the function 
using the JSR instruction. 

5. After control returns from the called function, adjust the stack 
pointer to account for pushed arguments (if any). 

For example, the following code calls the function cfunc with two 
parameters that are currently in registers D7 and D6 and stores the 
return code in the ret variable. 


XREF 

Scfunc 


MOVE . L 

D7,D1 


MOVE . L 

D6 , DO 


JSR 

Scfunc 

;call function 

MOVE . L 

DO, ret 

;save return value 


If your C function is declared using the asm keyword, you should 

pass the parameters in the appropriate registers, and if the function 
returns a structure or union, push a 4-byte pointer to a work area into 
which the return value can be copied. 

Instead of passing parameters into and out of a function, you can use 
global data. 

You can access data declared in an assembler module from a C 
function by placing the data declarations inside a data section and 
defining the data with an XDEF statement. The following code defines 
two variables in assembly language and shows how to declare them in 
a C function. 


In Assembly Language 
CSECT data 
XDEF VAR 1 , VAR2 , VAR 3 


In C Language 
extern long VAR 1 ; 
extern long VAR2 ; 


VAR 1 DC . L $4 000 
VAR2 DC.L $8000 



You can access data declared in a C function from an assembler 
module using the XREF statement, as follows: 

In C Language In Assembly Language 

long VAR1 =0x4000 ; XREF VARl,VAR2 

long VAR 1 = 0x4 0 00 ; 


MOVE . L VAR 1 , DO 


Running the Assembler 

After you have created your modules or programs in assembly 
language, you can run the Assembler by entering the asm command as 
follows: 

asm [>listfile] [ options ] filename 

Note: You can also use the s c command to run the assembler. 

The filename is the name of the assembly language source file that 
you want to assemble. The assembler assumes a source filename 
extension of . a, and it produces an object file with the same filename 
but with the . o extension. You can then use the slink command or 
the s c command to combine these object modules into an executable 
file, called a load module. 

If you include >listfile, the assembler sends the source listing and 
error messages to that file. 

The assembler supports the following options: 

-cx 

specifies that the sections designated by x are to be loaded into 
memory addressable by the Amiga system’s custom hardware. You 
should specify -c for screen image and audio data. The x can be 
one or more of the following: 

b bss or uninitialized data. The equivalent sc option is 
bssmem=chip. 

c code segment. The equivalent sc option is codemem=chip. 
d data segment. The equivalent sc option is datamem=chip. 
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By default, the assembler loads the segments into memory not 
addressable by custom hardware, if it is available. This action 
avoids bus contention between the processor and the custom 
hardware. For example, the following command causes all segments 
to be loaded into chip-addressable memory, regardless of the system 
memory configuration: 

asm -ccdb prog. a 


d 

activates the debugging mode. The equivalent s c option is 
debug=line. 

d symbol[=value] 

defines symbol as if your source file contained this statement: 
symbol EQU value 

If you do not specify a value, the assembler assigns a value of 1. 
The equivalent sc option is define, 
hx 

specifies that the sections designated by x are to be loaded into 
memory not addressable by the Amiga system’s custom hardware. 
The x can be one or more of the following: 
b bss or uninitialized data. The equivalent s c option is 
bssmem=f ast. 

c code segment. The equivalent sc option is codemem=f ast. 
d data segment. The equivalent sc option is datamem=f ast. 

By default, the assembler loads the segments into memory not 
addressable by custom hardware, if it is available. This action 
prevents the specified segments from being loaded into chip- 
addressable memory even if no other memory is available. This 
action could also prevent programs from running if external high- 
speed memory is not available on the machine. For example, the 
following command loads all three sections into high-speed RAM: 

asm -hcdb prog. a 

i prefix 

specifies a prefix that should be placed in front of filenames in 
INCLUDE directives. You can enter up to 16 -i options. The 
assembler will search for the files in the order in which you specify 



the prefixes. If you specify a directory name as a prefix, include the 
trailing slash (/). For example, you can assemble the file named 
testprog. a with the following command: 

asm -imyinc/ -iyourinc/ testprog. a 

If your program contains the statement include abc.i, the 
assembler searches for the file in the current directory. If that fails, 
it searches for myinc/abc . i and then your inc/abc . i. By 
default, the assembler automatically searches the current directory 
and include : . 

The equivalent sc option is includedirectory. 
jc 

suppresses messages to the console if you also specify - jm. If you 
do not specify - jm, then - jc is ignored. The equivalent sc option 
is noerrorconsole. 
jm 

sends messages to the scmsg utility. The equivalent sc option is 
errorrexx. 

1 [ x ] [m] [i] 

sends a listing of the source file to the standard output, usually the 
screen. The fisting displays the appropriate location counter and 
code- or data-generated information beside the source fine. The x, 
m, and i produce the following slightly different listings: 
x fists the expansion text for macros. The equivalent sc option is 
listmacro. 

m fists additional data generated for source fines that cannot be 
fisted beside the original source fine. This option allows multiple 
fisting fines for each source fine. The equivalent sc option is 
listnarrow. 

i fists the source for text from INCLUDE files as well as the 
original source file. The equivalent sc option is listheader. 

mO 

specifies that only 68000 instructions are allowed. This option 
issues warning messages if, for example, you use instructions that 
are only available on the 68020. This option is the default. The 
equivalent sc option is cpu=68000. 
m2 

turns off the warnings generated by the -mO option. Use this option 
if 68020 instructions are allowed.The equivalent sc option is 
cpu=68 020. 
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-m3 

turns off the warnings generated by the -mO option. Use this option 
if 68030 instructions are allowed. The equivalent sc option is 
cpu=68030. 

-m4 

turns off the warnings generated by the -mO option. Use this option 
if 68040 instructions are allowed. The equivalent sc option is 
cpu=68040. 

-o prefix 

specifies a prefix that you want placed in front of the output 
filename. If you specify a directory name as a prefix, include the (/). 
Any drive or directory prefixes in the input filename are discarded 
before the new prefix is added. Do not include blanks in the prefix. 
The equivalent sc option is objectname. 

-s 

includes the section name at the beginning of each hunk. 

-u 

specifies that you want the assembler to prefix external references 
with an underscore (_). Do not use this option if you entered all 
external names with leading underscores. You should specify this 
option when you assemble startup code. The equivalent sc option is 
underscore. 

-w 

defines the symbol short int to be 1. This option works as if you 
had specified -dshortint=1. The equivalent sc option is 
shortint. 

For example, the following command assembles the file named 
modn . a, produces an object file named modn . o, and generates a 
listing file named modn. 1st that lists the source code and any error 
messages: 


asm >modn.lst -1 modn 
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Introduction 

Your SAS/C Development System provides the following three 
optimizers: 

global optimizer (GO) 

analyzes the intermediate code produced by the compiler, performs 
several types of optimizations, and produces output in the same 
form as the compiler. Because the global optimizer works on 
intermediate code, it has no knowledge of the target processor or its 
instructions, 
peephole optimizer 

analyzes the assembler instructions and replaces inefficient 
sequences of instructions with shorter, more efficient sequences, 
scheduler 

changes the order of instructions to create code that runs faster on 
the 68040 CPU or 68882 math coprocessor. 


The Global Optimizer 

The global optimizer optimizes the flow of control and data through an 
entire function. The global optimizer performs several types of 
optimizations: 

register assignment 

analyzes the function to determine which auto variables, formal 
variables, temporary values, and constant values should be assigned 
to registers at each point in the function. The optimizer assigns up 



to three address registers, four data registers, and, if a math 
coprocessor is present, four floating-point registers for the use of 
register variables. 

Generally speaking, the variables that are most used at a given 
point are assigned to registers. For example, variables occurring in 
loops are more likely to be assigned to registers. The global 
optimizer attempts to keep a variable assigned to a register for as 
long as possible. 

Using the ampersand (&) operator with a variable prevents the 
global optimizer from allocating that variable to a register because 
it cannot predict when the resultant pointer will be used to read or 
modify the variable’s value in memory. The same condition applies 
to an external variable because it may appear in another function 
or the & operator may be used with it elsewhere. 

The effect of global optimization’s register allocation is quite 
different from the use of the register storage class. In general, a 
variable declared using the register keyword is associated with a 
machine register throughout the entire block in which it is declared 
(usually the entire function). In most functions, the variable is 
heavily used in some places and not used in other places. Yet, if a 
machine register is assigned to the variable, then the same register 
cannot be reused even in those sections where the variable is not 
used. Therefore, global optimization changes a register’s assigned 
variable during the evaluation of the expression to ensure that the 
most heavily used variables are always in machine registers. 

The global optimizer overrides the register keyword in the 
declarations of integer, double, and pointer variables. Because of 
the portability of the C language, it is difficult for a programmer to 
know the number of available registers provided by the target 
machine and the compiler. The concept of a register variable is 
based on the idea that the variable is kept in a register for the 
entirety of its scope. Such restrictions no longer apply when a 
compiler uses the more advanced registration allocation algorithms 
in SAS/C software. Even though the compiler does not have 
dynamic information about program execution that would indicate 
which statements are executed more heavily, it can use the loop 
nesting structure to make a reasonable approximation. 
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dead store elimination 

eliminates the assignment of a value to a variable if the value is not 
used. The assignment can be eliminated as in this example: 

index = 23; 

/* code that does not refer to index */ 
index = 12; 

The first assignment to index can be removed. Since the global 
optimizer inspects all references to the variable throughout the 
entire function, even subtle dead stores are eliminated. 

dead code elimination 

eliminates code that never can be executed, including static 
function definitions that are never referenced, 
common subexpression merging 

eliminates recalculation of values that have been computed 
previously within the same function. For example, the following 
code 

x = i / 3; 
y = i / 3 + 4; 

can be changed to 

temp = i / 3; 
x = temp; 
y o temp + 4; 



moving invariants out of loops 

moves a calculation in a loop, whose value is the same on each 
iteration, to the outside of the loop. For example, the loop 

for (i = 0; i < j; i++) 

( 

a [ i 1 = p->q.r [ 10] ; 

) 


can be changed to 

temp = p->q.r [ 10 ] ; 
for (i = 0; i < j; i++) 
( 

a [ i ] = temp; 

) 


Refer to the explanation for opt loop later in this chapter for 
more information about this type of optimization, 
induction variable transformations 

changes to addition loops containing multiplications (usually those 
associated with array indexing), 
copy propagation 

eliminates definitions of the form leftvar = rightvar when all 
uses of leftvar have this definition as the single reaching 
definition and rightvar will not change before each use. This 
optimization supports other optimizations. 
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constant propagation and folding 

replaces references to a variable with a constant when the variable 
is defined as that constant. If the variable is used only in 
expressions with a different type (for example, if an int variable is 
only used in a comparison with float variables), global 
optimization creates a constant of the correct type. If the variable is 
used only as a constant, global optimization eliminates the variable 
entirely. The following example demonstrates these optimizations: 


void f(double d) 

{ 

i = 10; 

for ( ; d < i ; ++d) 

( 

/* more code */ 

) 

return; 

) 


The previous code can be changed to the following: 

void f(double d) 

( 

for ( ; d < 10.0; ++d) 

( 

/* more code */ 


return; 

} 

Constant propagation is often useful in programs that contain 
inline functions since one or more parameters to the inlined 
function actually may be constants, 
auto variable elimination and remapping 

eliminates unused auto variables and reassigns storage offsets. Often 
the variable is unused because of previous optimizations. 
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very busy expression hoisting 

moves an expression that is computed along all paths from a point 
in the code to a single, common location. For example, the code 

if (expression) 
x = i + j; 
else 

y = (i + j) * 2; 

can be changed to 

temp = i + j ; 
if ( expression ) 
x = temp; 
else 

y = temp * 2; 

various reductions in strength 

performs associative reordering of additive operations involving 
constants to reduce the operation count. 

Various arithmetic operations involving constants are reduced in 
strength. 

Conditional and logical expressions whose results are unused are 
converted into corresponding if code. For instance, put char 
from stdio .h is implemented with a conditional expression. If the 
result (the original character or an error indication) is not used, GO 
converts it into if else code, eliminating a load into a register, 
various control flow transformations 

performs various transformations to eliminate unreachable code or 
useless control structures, 
reordering of operations to reduce value lifetimes 

moves expressions with a single use adjacent to the operation that 
uses them. This optimization helps reduce temporary lifetimes and 
supports optimizations that move code around. For example, in the 
following code, the computation of the address 6 p [ i ] can be 
moved after the call: 


p[i] = f(); 
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The Peephole Optimizer 

The code generator contains all of the knowledge about the target 
processor and its instructions and makes full use of the 680x0 
instruction set. The code generator tries not to generate extra 
instructions, but the peephole optimizer can help catch the few places 
where this is not possible. 

As stated earlier, the peephole optimizer analyzes the assembler 
instructions and replaces inefficient sequences of instructions with 
shorter, more efficient sequences. For example, for the following set of 
instructions, the peephole optimizer deletes the TST.L instruction: 

MOVE . L D 1 , D2 

TST.L D2 

BNE LABEL 

The test instruction is not needed because the condition codes for the 
branch instruction are set by the move instruction. 

Currently, the peephole optimizer optimizes many patterns of 
assembler instructions. If you find additional patterns that the 
optimizer should recognize, contact the Technical Support Division at 
SAS Institute Inc. 


The Scheduler 

The 68040 and 68882 chips are capable of running some instructions 
in parallel. For example, you can do a floating-point multiply at the 
same time as an integer multiply. The instruction scheduler moves 
instructions around to make the most use of this feature. The resulting 
code still works on all processors, but it runs faster on the target 
processors. 
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Running the Optimizers 

To run the optimizers, specify the appropriate compiler option: 


Option Effect 


optimize turns on both the global and peephole 

optimizers. 

optimize turns on only the global optimizer, 

nooptpeep 

optimize turns on only the peephole optimizer, 

nooptglobal 


optimize turns on the global and peephole optimizers and 

optschedule the instruction scheduler. 


In many cases, optimized code is more difficult to debug than non- 
optimized code. You may want to use the optimizer only after the main 
program has been tested and most errors have been corrected. 


Global 

Optimization 

Compiler 

Options 


The compiler accepts the following options to modify the operation of 
the global optimizer: 

optalias 

disables type-based aliasing assumptions. If optalias is used, the 
global optimizer uses worst-case aliasing. Using this option can 
significantly reduce the amount of optimization that can be 
performed. The nooptalias option is the default. 


opt complexity 

defines the complexity of functions considered small by 
opt inline. For more information, refer to Chapter 8, “Compiling 
and Linking Your Program,” of SAS/C Development System User’s 
Guide, Volume 1: Introduction, Compiler, Editor. 


optdepth 

defines the maximum depth of function calls to be Mined. The 
range is 0 to 6, and the default value is 3. 


optinline 

inlines small functions (as defined by opt complexity) as well as 

those with the inline keyword. The optinline option is the 

default when optimize is used. Refer to Chapter 11, “Using 
SAS/C Extensions to the C and C++ Languages,” in the SAS/C 
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Development System User’s Guide, Volume 1, for information about 

the inline keyword. 

optinlocal 

inlines single-call static (local) functions, 
optloop 

assumes that loops have multiple iterations when the number of 
iterations is variable. This assumption enables the movement of safe 
code out of loops. The optloop option is the default. For more 
information, see “moving invariants out of loops,” earlier in this 
chapter. 

When a loop is not executed at all, the moved code is executed in 
cases where it previously would not have been. For example, the 
code 


for (i = 0; i < n; ++i) 
for (j = 0; j < m; ++ j ) 
p[i * m + j ]+= 1 ; 

can be changed to 

for (i = 0; i < n; ++i) 

{ 

temp = i * m; 
for (j = 0; j < m; ++ j ) 
p[temp + j ]+= 1 ; 

) 


In the changed code, i *m can be calculated when m is less than or 
equal to 0. When optloop has been specified, there may be a 
small cost in time for every loop that is not executed. There is also 
a significant time saving for loops that are executed many times, as 
most are. 

Some types of code may cause an exception, for example, division 
by 0. For this reason, the global optimizer restricts moved code to 
safe operations, including integral and pointer arithmetic other than 
division by 0, but not including floating-point operations. The global 
optimizer avoids incorrect exceptions regardless of the setting of 
optloop. 
optrdepth 

defines the maximum level of recursive function calls to be inlined. 
The range is 0 to 6, and the default is 1. 
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Optimization 
and the 
Debugger 


optsize 

generates smaller code, possibly increasing execution time. The 
nooptsize option is the default, 
opttime 

generates code that will run faster but may be larger. The 
noopttime option is the default. 

To use all the capabilities of the debugger, the lines in the source code 
file must correspond exactly with the lines in the object code file. 
Optimizing your code may change this correspondence. Also, the 
debugger may not know about variables that the optimizer moves or 
eliminates. 

If you use the debugger on optimized code, run the debugger in 
mixed mode by entering the following command on the debugger 
command line: 

opt source mixed 

In mixed mode, the debugger displays both assembly language 
instructions and C source lines in the source window. Use the 
assembly language code to determine if the variables you examine are 
actually located where the debugger thinks they are. 



349 



Appendices 


Part 5 

Appendices 


1 diff File-Matching Algorithm 

2 Source Code for Debugger Examples 


350 



351 


Appendix 1 

diff File-Matching Algorithm 

This appendix describes the file-matching algorithm used by the diff 
utility. The algorithm used by the diff utility is described in A 
Technique for Isolating Differences Between Files by P. Heckel.* 

The matching algorithm described by Heckel is simple, fast, and 
effective. Briefly, it works as follows: 

□ Identify those lines that occur only once in each file. Assume that 
these lines match one another. 

□ Sweep downward into the first file. Each time you come to a line L 
that is already matched to the line L 1 in the second file, examine the 
next line. This second line is referred to as L+l. 

□ If L+l is the same as the corresponding line L* + l in the second 
file, then match those lines as well. 

□ After this downward sweep is completed, sweep upward in the first 
file attempting to match lines in the same way (except that you look 
at L— 1 and L 1 — 1 when finding a matched line L). 

The effect of the matching algorithm is to match blocks of text to each 
other in the two files. 

However, the algorithm frequently cross-matches single lines or two 
blocks of lines. That is, lines L and L+k may be matched to lines L 1 
and L 1 — j. Consequently, after the process described previously is 
completed, the matches must be untangled to generate a coherent 
report of the differences. Therefore, the diff utility cross-matches 
blocks and then unmatches the smaller of the blocks. This process is 
an attempt to satisfy the notion that the differences reported should be 
minimal. 

In addition, this algorithm must first seed itself by identifying lines 
that occur exactly once in each file. Therefore, this algorithm may fail 
to match any lines even when there is an obvious match. 


* Heckel, P. (1978), “A Technique for Isolating Differences Between Files,” 
Communications of the ACM (April), 264-8. 
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For example, you may have two files with the following contents: 

File 1 File 2 
aaa bbb 

xxx xxx 

xxx xxx 

yyy zzz 


The algorithm will fail to match the blocks of xxx lines because it does 
not find any lines that occur exactly once in each file to seed the 
algorithm. 
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Appendix 2 

Source Code for Debugger 
Examples 

353 Introduction 

353 smain.c 

354 sort.c 

355 swap.c 
355 chess l.cxx 

358 mylib.c 

359 mylib.fd 

359 test.c (for shared libraries) 

360 process.c 

362 test.c (for child processes) 

364 loop.c 
364 dummy.c 
364 serial. c 
369 driver.c 


Introduction 

This appendix contains the source code for the example programs used 
in Chapters 3 through 6. 


smain.c 

jfdefine ASIZE 10 

void init(int *, int ) ; 
int sort( int *, int) ; 
void printArr(int *, int); 

int array[ASIZE] ; 

int main(void) 

( 

init(array, ASIZE) ; /* initialize array */ 


/* Keep swapping elements until sorted */ 
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while (sort(array,ASIZE) != 0) 


printArr( array, ASIZE) ; 
return 0; 


sort.c 

iinclude <stdio.h> 

void swap(int *, int *); 

void init(int *arrayPtr, int size) 

( 

int i; 
int *ptr ; 

ptr = arrayPtr; 
for (i=1; i < size - 1; i++) 
*ptr++ = i; 


/* Reverse sort the elements of the array */ 

int sort(int *arrayPtr, int size) 

{ 

int i, swapped; 
int *ptr ; 

ptr = arrayPtr; 
swapped = 0; 

for (i=0; i < size; i++) 
if (ptr [ i 1 < ptr [ i+1 ) ) 

( 

swap(6ptr[i] , 6ptr[i+1]); 

swapped =1; /* indicate a swap took place */ 

} 


return swapped; 
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/* Print the array */ 

void printArr(int *arrayPtr f int size) 

( 

int i ; 
int *ptr; 

ptr = arrayPtr; 

for (i=1; i < size - 1; i++) 

printf ( "array[Sd] is 55d\n" , i , *ptr++) ; 


swap.c 

void swap(int *x, int *y) 

{ 

int tmp; 


*x = *y ; 
tmp = *x ; 
*y = tmp; 


chessl.cxx 

// This C++ example is a very basic chess program. 
// This version contains a logic error that will 
// be found with the CodeProbe debugger. 


flinclude <iostream.h> 
iinclude <string.h> 



class chessPiece ( 

char name[ 10 ] ; 

// 

full name of the piece 

char color; 

// 

is it white or black 

char code; 

// 

display abbreviation 

int value; 

// 

value of piece in points 


public: 

chessPiece(const char *n, char c, char co, int v) { 
// construct and initialize a chess piece 
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strcpy(name, n); 
color = c; 
code = co; 
value = v; 


void showPiece( ) { 

// display the piece to the user 
cout << "I " << color << code << 

} 


class chessBoard ( 

class chessPiece *board[8 ] [8 ] ; // the chess board 

public: 

chessBoard( ) ; 

~chessBoard( ) ; 

void showBoard(); 

void movePiece( int old_r, int old_c, int new_r, int new_c); 

); 


chessBoard: :chessBoard( ) { 

// Take out the pieces and setup the board 
int r,c; 

for (r=0; r<8 ; r++) 
for (c=0; c<8; C++) 
board [r ] [ c ] = NULL; 

for (c=0; c<8; C++) ( 


board [ 1 ] [ c ] = new chessPiece ("pawn 

, 

'w', ' P ' , 1 

board[6][c] = new chessPiece ("pawn 

) 


' b ' , ' P • , 1 

board( 0] [0] 

= new 

chessPiece 

[ "rook" , 

w 

, 'R\ 5); 

board! 0] [7] 

= new 

chessPiece 

[ "rook" , 

w 

, 'R\ 5); 

board [7)10] 

= new 

chessPiece 

( "rook " , 

b 

, ’R\ 5); 

board! 7 ] [ 7 ] 

= new 

chessPiece 

( "rook" , 

b 

, 'R\ 5); 

board! 0] 1 1 1 

= new 

chessPiece 

( "knight" 


w' , 'N' , 3) 

board[0] [6] 

= new 

chessPiece 

( "knight" 


w' , 'N' , 3) 

board! 7 ] [ 1 ] 

= new 

chessPiece 

( "knight" 


b' , 'N' , 3) 
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board[ 7 ] [6] 

= new 

chessPiece 

; "knight" 

' ' 

, 'N', 3) ; 

board! 0] [2] 

= new 

chessPiece 

; "bishop" 

' w' 

, 'B\ 3); 

boardIO] (5] 

= new 

chessPiece 

; "bishop" 

'w' 

, ' B ' , 3); 

board [ 7 ] ( 2 ] 

= new 

chessPiece 

; "bishop" 

■ b ’ 

, 'B', 3); 

board(7] 1 5 

= new 

chessPiece 

"bishop" 

' b ’ 

, 1 B ' , 3); 

board[0] 1 3 

= new 

chessPiece 

"queen" , 

1 w ' , 

'O', 9); 

board! 7 1 [ 3 ] 

= new 

chessPiece 

"queen" , 

' b ' , 

'O', 9); 

board[0] ! 4 

= new 

chessPiece 

"king" , 

w' , 

'K' , 3); 

board! 7 ] [ 4 ] 

= new 

chessPiece 

"king" , 

b' , 

'K' , 3); 


chessBoard: :~chessBoard( ) { 

// put the pieces back in the box 
int r, c; 

for (r=0; r<8; r++) 
for ( c=0 ; c<8; C++) 
delete board[r ] [c] ; 

} 

void chessBoard: :movePiece( int old_r, int old_c, 

int new_r, int new_c) { 

// perform a simple piece move 

// ! ! ! this statement contains a logic error!!! 
board [ new_c ] [new_r] = board[oldL_r][old_c); 

board [ old_r ] [old_c] = NULL; 

) 

void chessBoard: : showBoard( ) { 

// display the chess board as a grid containing 
// the pieces in their current position, 
int r,c; 

for (r=7; r>=0; r — ) ( 

cout << " " << endl; 

for ( c=0 ; c<8; C++) 

if ( board[ r] [c] != NULL) 
board[r] [c]->showPiece( ) ; 
else cout << "I " ; 
cout << ' I ' « endl; 
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) 

cout << " " << endl 


int main ( ) ( 

// constructs and setups up the pieces 
class chessBoard gameboard; 

// start the game with the Sicilian opening 
gameboard. movePiece( 1 , 4 , 3,4); 
gameboard. movePiece(6, 2, 4,2); 
gameboard. movePiece( 0,6, 2,5); 
gameboard. movePiece( 7 , 1 , 5,2); 

// display the board to the user 
gameboard . showBoard ( ) ; 

// the game board and chess pieces are automatically 
// (put away) destructed 

return 0; 


mylib.c 

int b = 0 ; 

asm saveds LIBtestl ( void) 

( 

return(b) ; 

) 

asm saveds LIBtest2(register dl int a) 

{ 

b = a; 
return(b) ; 
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mylib.fd 

iibase -MyLibBase 
ISbias 30 
test 1 ( ) 
test2(a) (D1 ) 

S#end 


test.c (for shared libraries) 

iinclude "proto/exec. h" 
iinclude "proto/dos .h" 
iinclude "mylib_pragraas .h" 
iinclude <stdio.h> 

char — stdiowin[] = "con: 0/0/640/100/" ; 
struct Library *MyLibBase; 

main( ) 

{ 

int ret; 

MyLibBase = OpenLibrary( "mylib. library" , 0 ) ; 

if (MyLibBase) 

( 

printf ( "Library Opened Sucessfully. \n" ) ; 
ret = testl ( ) ; 

printf ( "test 1 returned = 5Sd\n", ret); 
test2(ret+1 ) ; 

printf ( "test 1 returned = 5Sd\n" , testl ()) ; 

CloseLibrary(MyLibBase) ; 
printf ( "Library Closed. \n" ) ; 

Delay( 200 ) ; 

) 
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process.c 

finclude "process. h" 

void process_starter (void) 

{ 

struct Process *proc; 
struct ProcMsg *mess; 
long (*fp)(void); 

proc = (struct Process *)FindTask( (char *)NULL); 

/* get the startup message */ 

WaitPort( 6proc->pr_MsgPort) ; 

mess = (struct ProcMsg *)GetMsg( 6proc->pr_MsgPort ) ; 

/* gather necessary info from message */ 
fp = mess->fp; 

putreg(REG_A4, (long)mess->global_data) ; 


/* Call the desired function */ 
mess->return_code = (*fp)(); 

/* Forbid so the child can finish completely, before */ 
/* the parent cleans up. */ 

Forbid ( ) ; 

/* Reply so process who spawed us knows we're done */ 
ReplyMsg( ( struct Message *)mess); 


struct ProcMsg *start_process( fp, priority, stacksize) 

long ( *fp) ( void) ; 

long priority , stacksize ; 

{ 

struct MsgPort *child_port; 
struct ProcMsg *start_msg; 
struct FAKE_SegList *seg_ptr; 

/* Allocate memory for both fake seglist and startup */ 
/* message. If either fail we can return, before */ 
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/* the CreateProc( ) . */ 

seg_ptr = (struct FAKE_SegList *)AllocMera( sizeof (*seg_ptr), 

MEMF—PUBLIC) ; 

if (seg_ptr == NULL) return NULL; 

start_msg = (struct ProcMsg *)AllocMem(sizeof (struct ProcMsg), 

MEMF_PUBLIC I MEMF_CLEAR ) ; 

if (start_msg == NULL) 

{ 

FreeMem(seg_ptr, sizeof (*seg_ptr)); 
return NULL; 

} 


/* Fill in Fake SegList */ 
seg_ptr->space = 0; 

seg_ptr->length = (sizeof (*seg_ptr) + 3) 6 ~3; 
seg_ptr->nextseg = NULL; 

/* Fill in JMP to function */ 

seg_ptr-> jmp = 0x4EF9; /* JMP instruction */ 

seg_ptr->func = process_starter ; 

/* If we're running under 2.0 it's possible to be */ 

/* on a 68040. Therefore the cache needs to be */ 

/* flushed before the child can start executing. */ 
if (SysBase->LibNode.lib_Version >= 36) 

CacheClearU( ) ; 

/* create the child process */ 
if ( (child_port = CreateProc( "New Process", 
priority, 

( BPTR) ( ( long) Sseg_ptr->nextseg>>2) , 
stacksize) ) == NULL) 

{ 

/* error, cleanup and abort */ 

FreeMem( seg_ptr , sizeof ( *seg_ptr ) ) ; 

FreeMem( start_msg, sizeof ( *start_msg) ) ; 
return NULL; 

) 

/* Create the startup message */ 

start_msg->msg.mn_Length = sizeof ( struct ProcMsg) - 
sizeof ( struct Message); 

start_msg->msg.mn_ReplyPort = CreatePort( 0 , 0 ) ; 
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start_msg->msg.mn_Node.ln_Type = NT—MESSAGE ; 

/* save global data reg (A4) */ 
start_msg->global_data = (void *)getreg(REG_A4 ) ; 

start_msg->seg = seg_ptr; 

start_msg->fp = fp; /* Fill in function pointer */ 

/* send startup message to child */ 

PutMsg(child_port , (struct Message * ) start_msg) ; 

return start_msg; 

} 

long wait_process ( start_msg) 
struct ProcMsg *start_msg; 

( 

struct ProcMsg *msg; 
long ret; 

/* Wait for child to reply, */ 

/* signifying that it is finished */ 
while ((msg = (struct ProcMsg *) 

WaitPort( start_msg->msg.mn_ReplyPort ) ) != 
start_msg) 

ReplyMsg( (struct Message *)msg); 

/* get return code */ 
ret = msg->return_code; 

/* Free up remaining resources */ 
DeletePort(start_msg->msg.mn_ReplyPort) ; 

FreeMem( ( void *)start_msg->seg, sizeof ( struct FAKE_SegList ) ) ; 
FreeMem( ( void *)start_msg, sizeof (*start_msg) ) ; 

return(ret ) ; 

) 


test.c (for child processes) 

/* Example program that uses the */ 

/* functions define in process. c */ 
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((include "process. h" 

long processl (void) 

{ 

long out; 
char buf f [ 1 ] ; 
char *a; 

/* Cause an enforcer hit */ 
a = NULL; 

*a = 0; 

out = Open( "CON: 10/120/520/80/New Process 1", 
if (out == NULL) return -1; 

Write(out, "Hit Return to Close WindowNn", 27) 
Read (out, buff, 1); 

Close(out) ; 
return 1 ; 


main(argc, argv) 
int argc; 
char *argv[ ] ; 

( 

struct ProcMsg *start_msg1; 
long ret; 

/* Start process 1 */ 

start_msg1 = start-process ( process 1 , 0, 4000); 
if (start_msg1 == NULL) 

( 

printf ( "Can 1 t start process 1\n"); 
exit( 1 ) ; 


/* Wait for processes to finish */ 

ret = wait_process (start_rasg1 ) ; 

printf ( "Return from process 1 is Xd\n",ret); 


MODE-OLDFILE) ; 


exit(0) ; 



364 Appendix 2 


loop.c 

/* example program that runs forever */ 

({include <stdio.h> 

{{include <proto/exec .h> 

main( ) 

( 

int i = 0; 
struct Task *Task; 

/* set priority to -1 so we don't use up all the CPU */ 
Task = FindTask( 0) ; 

SetTaskPri(Task, -1); 


while (i == 0) 

( 

printf ( "looping ...\n"); 

) 


dummy.c 

/* Small dummy program */ 

main( ) 

{ 

return 0; 

) 


serial.c 

/* Example device that implements the CMD_READ and CMD—WRITE */ 
/* commands. This device will only run under AmigaDOS 2.0 or */ 
/* greater because of the use of CreateNewProc( ) . */ 

{{define _USEOLDEXEC_ 1 
finclude <exec/types .h> 

^include <exec/nodes .h> 
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{{include <exec/memory .h> 

{{include <exec/resident.h> 
{{include <exec/libraries .h> 
{{include <exec/execbase.h> 
{{include <exec/io.h> 

{{include <exec/errors ,h> 

{{include <libraries/dos .h> 
{{include <devices/serial .h> 
{{include <dos/dostags .h> 

{{include <utility/tagitem.h> 
{{include <proto/exec.h> 

{{include <proto/dos .h> 

{{include <string.h> 

{{include <dos.h> 

idefine CMD—TERM 0x7ff0 
{{define CMD_STARTUP 0x7ff1 

struct MsgPort *myPort; 
extern struct ExecBase *SysBase; 

struct START_MSG ( 

struct Message msg; 
long devbase; 

}; 


void cmd_handler ( void) 

{ 

struct IORequest *ior; 
struct IOExtSer *ioes; 
long input, output; 
struct Process *proc; 
struct START_MSG *msg; 

proc = (struct Process * )FindTask( ( char *)NULL); 

/* get the startup message */ 

while((msg = (struct START—MSG * )GetMsg( 6proc->pr_MsgPort) ) 
== NULL) 

WaitPort ( 8proc->pr_MsgPort ) ; 

/* builtin compiler functions to set A4 to the global */ 

/* data area */ 
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putreg(REG_ A6 , msg->devbase) ; 
geta4( ) ; 

myPort = CreatePort(0, 0) ; 

ReplyMsg( (struct Message *)msg); 

if (myPort == NULL) return; 

input = Open( "con: 0/0/400/ 100/Input" , MODE—NEWFILE) ; 
if (input == NULL) return; 

output = Open( "con: 0/1 10/400/ 100/Output" , MODE—NEWFILE) ; 
if (output == NULL) 

( 

Close( input ) ; 
return; 

] 


while (1) 

{ 

WaitPort(myPort) ; 

while (ior = (struct IORequest * )GetMsg( myPort ) ) 

{ 

switch( ior->io_Command) 

( 

case CMD— TERM : 

Close( input ) ; 

Close(output ) ; 

Forbid( ) ; 

ReplyMsg( Sior->io_ Message) ; 
return; 

case CMD-READ: 

ioes = (struct IOExtSer *)ior; 
ioes->IOSer.io_Actual = Read(input, 

ioes->IOSer.io_Data f 
ioes->IOSer . io_Length) ; 

break; 

case CMD—WRITE: 

Write (output, ioes->IOSer . io_Data, 
ioes->IOSer.io_Length) ; 

break; 

) 

ReplyMsg( 6ior->io_Message) ; 
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int saveds asm UserDevInit(register dO long unit, 

register aO struct IORequest *ior, 

register a6 struct MyLibrary *libbase) 

( 

struct Process *myProc; 
struct START-MSG msg; 

if (SysBase->LibNode.lib_Version < 36) 

return 1; /* can only run under 2.0 or greater */ 

myProc = CreateNewProcTags (NP_Entry, cmd—handler, 
NP_StackSize, 4096, 

NP_Name , "CMD_Handler" , 

TAG-DONE ) ; 

if (myProc == NULL) 
return 1 ; 

/* Send the startup message with the library base pointer */ 
msg.msg.mn_Length = sizeof ( struct START—MSG) - 
sizeof (struct Message); 
msg.msg.mn—ReplyPort = CreatePort(0, 0) ; 
msg.msg.mn_Node. ln_Type = NT-MESSAGE; 
msg.devbase = getreg(REG_A6 ) ; 

PutMsg( SmyProc->pr_MsgPort, (struct Message *)Smsg); 

WaitPort (msg.msg.mn—ReplyPort) ; 

if (myPort == NULL) /* CMD_Handler allocates this */ 
return NULL; 

DeletePort(msg.msg.mn_ReplyPort) ; 
return 0; 

) 


void saveds asm UserDevCleanup( register — aO 

struct IORequest *ior, 

register a6 

struct MyLibrary *libbase) 
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struct IORequest newior; 

/* send a message to the child process to shut down. */ 
newior. io_Message.mn_ReplyPort = CreateMsgPort( ) ; 
newior . io_Command = CMD—TERM ; 
newior . io_Unit = ior->io_Unit ; 

PutMsg(myPort , 6newior.io_Message) ; 

WaitPort ( newior . io_Message .mn_ReplyPort ) ; 

DeleteMsgPort ( newior . io_Message.mn_ReplyPort ) ; 
DeletePort(myPort ) ; 


void saveds asm DevBeginIO(register al 

struct IORequest *ior) 


ior->io_Error = 0; 

ior->io_Flags 6= ~IOF_QUICK; 
switch(ior->io_Command) 

{ 

case CMD—READ: 
case CMD—WRITE : 

PutMsg(myPort , 6ior->io_Message) ; 
break; 

case CMD—RESET : 
case CMD—UPDATE : 
case CMD—CLEAR: 
case CHD_STOP: 
case CHD_START : 
case CMD—FLUSH: 
case CMD—INVALID : 
default: 

ior->io_Error = IOERR_NOCMD ; 
ReplyMsg(6ior->io_Hessage) ; 
break; 
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void saveds asm DevAbortIO(register al 

struct IORequest *ior) 

( 

} 


driver.c 


/* Driver program to test example. device */ 

^include <exec/devices .h> 

((include <devices/serial .h> 
finclude <proto/exec.h> 


void main(void) 

{ 

struct IOExtSer *ior; 
struct MsgPort *SerialMP; 
char buff [ 10) ; 


if (SerialMP = CreatePort(0, 0) ) 

{ 

if (ior = (struct IOExtSer *) 

CreateExtIO(SerialMP, sizeof ( struct IOExtSer))) 

{ 

if (OpenDevice( "example. device" ,-1 , 

(struct IORequest* ) ior, 0) ■= 0) 

( 

ior->IOSer.io_Data = buff; 
while( 1 ) 

{ 

ior->IOSer . io_Coramand = CMD_READ ; 
ior->IOSer . io_Length = 1; 

DoIO( (struct IORequest *)ior); 
if ( ior->IOSer . io_Actual < 1) 


CloseDevice( (struct IORequest *)ior); 
break; 


ior->IOSer . io_Command = CMD—WRITE ; 
ior->IOSer . io_Length = 1; 

DoIO( (struct IORequest *)ior); 
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) 

DeleteExtI0( (struct IORequest *)ior); 


) 


DeletePort(SerialHP) ; 
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Glossary of Debugger 
Terms 


breakpoint 

is an address used to control program execution. Program execution 
is suspended when the breakpoint address is reached, 
call frame 

is the stack area associated with a function’s formal parameters, 
automatic variables, temporaries, saved registers, and the return 
address. There is one call frame per function invocation, 
cross-debugging 

is a debugging technique that uses two machines that are linked 
together. CodeProbe runs on one machine, and the application runs 
on the other. See also host machine and target machine. 

environment 

in CodeProbe documentation, environment means the state of the 
machine. The state of the machine consists of the contents of 
memory, the contents of the registers, the contents of the stack, and 
the point of execution in the source code. 

The run environment is the current state of the machine at the 
point at which you are stopped. 

The user environment is the last environment set with the env 
command or the current environment if the env command has not 
been entered. This environment is used when displaying registers 
and variables. It is reset to the run environment after a go 
command or any of the commands that step the program, 
host machine 

when cross-debugging, the host machine is the machine that is used 
to display the CodeProbe user interface. The actual debugging 
session takes place on this machine. See also cross-debugging, 
image 

is an executable program, an AmigaDOS shared library, or an 
AmigaDOS device. The name of the image is the same as the name 
of the disk file from which the image is loaded. An image can be 
specified with several CodeProbe commands as part of the location 
parameter, 
line boundary 

is the imaginary boundary in the machine code that is the end of 
the machine code generated for an individual C source line. 



log file 

is a file created by CodeProbe that contains details of all of the 
activity that occurred in the Dialog window. A log session can be 
turned off and on with the log command. By default, the log file is 
turned off. 
module 

is all code generated for a single C source file. The name of the 
module is the same as the name of the C source file for which it 
was generated, 
pass count 

is the number of times that a line has been executed. The after 
parameter is used with commands such as go and break to specify 
a pass count, 
run environment 

is the actual environment, or current state of the machine, at which 
your program is stopped. See also environment, 
symbol 

is a series of letters and numbers that specify a function, memory 
location, or a variable, 
target machine 

when cross-debugging, the target machine is the machine used to 
run the application. See also cross-debugging, 
user environment 

is the last environment set with the env command or the current 
environment if the env command has not been entered. This 
environment is used when displaying registers and variables. See 
also environment. 
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A 

-a option 

scompare utility 263 
smake utility 285 

Abort Build option, scmsg Build menu 254 
abort command, SC—SCMSG A RE XX port 257 
-abort option, quit command 159 
absolute expressions, assembler statements 312 
actions, smake utility 270 
actions gadget 265 
activate command 81, 110 
examples 110 
active window 13-17 
address command 97 
address parameter 26 
addresses 

absolute addressing modes 322 
addressing modes supported by SAS/C assembler 
320-321 

counter-relative addressing modes 322 
register-indirect addressing modes 321 
specifying immediate data 322 
specifying with CSECT assembler directive 319-322 
specifying with SECTION assembler directive 317-318 
AddSCMSG function, smfind utility 290 
addsym option 8 
slink command 36 
after option 
break command 117 
go command 140 
alias command 43-46, 111 
creating aliases 43-46 
displaying alias definitions 43 
displaying aliases 43 
examples 111 
aliases 43-46 
creating 43-46 
displaying 43 
displaying definitions 43 
dump command 129-130 
align parameter, CSECT assembler directive 318 
alternate targets, smake utility 280-281 
altfile command, SC—SCMSG AREXX port 257 
altline command, SC_SCMSG AREXX port 257 
AmigaDOS wildcards 217, 288 


ampersand (&) 
global optimizer 340 
smake utility 274 
append block, diff utility 214 
AREXX interface, scmsg utility 249, 256-261 
AREXX macros 93-97 
debugger command output 96-97 
debugger command return codes 96 
displaying list of loaded libraries 74-75 
invoking 95 
list 93-95 

using macros from outside of CodeProbe 97 
args command 112 
examples 112 

args option, where command 191 

array-slice parameter 27 

arrays, displaying 52-63 

arrdim option, opt command 151 

ASCII literals, specifying in assembler statements 311 

asm command 332 

asm keyword, calling assembler functions from C 

functions 327-329 
assembler directives 312-316 
See also specific assembler directives 
assembly language 307-335 
See also calling assembler functions from C functions 
See also specific assembler directives 
calling C functions from assembler functions 330-331 
defining and using macros 316 
defining control sections 317-322 
directives 312-316 

options supported by assembler 332-335 
referencing global data 331-332 
running assembler 332-335 
writing assembler statements 308-312 
asterisk (*) 

array-slice parameter 27 
bclear command 113 
bdisable command 114 
benable command 115 
blist command 116 
display command 126 
grep utility 219, 223 
removing aliases 46 
removing macros 48 
undefine command 184 
wclear option 187 
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asterisk (*) (continued) 
wdisable command 188 
wendable command 189 
asynchronous tasks 79 
at sign (@) 

assembler statements 311 

calling assembler functions from C functions 327 

calling C functions from assembler functions 331 

oml utility 245 

smake utility 274 

auto variable elimination and remapping 343 
autoedit option 

hide command, SC—SCMSG AREXX port 259 
scmsg utility 249 

autoinitialization function, sprof utility 298-299 
autoswap option, opt command 151-152 
autotermination function, sprof utility 298-299 
avail macro 93 


B 

-b option 
diff utility 212 
oml utility 247 
smake utility 285 
backslash (\) 

\;, alias command 44 
\;, echo command 132 
Control-\ for terminating oml 245 
define command 48 
escape characters 35 
escape sequences 32 
extending commands across lines 19, 71 
grep utility 220, 225-226 
location parameter 29 
smake utility 272, 274 
string parameter 32 
\ (backslash) 

See backslash (\) 
backtick character Q 
macro definitions 46 
referencing aliased commands 45-46 
badchar option, opt command 152 
baud rate, cross-debugging using serial port 100 
bclear command 113 
examples 113 
bdisable command 114 
examples 114 
benable command 115 
examples 115 


blist command 116 

bottom command, SC—SCMSG AREXX port 257 
BRA branch instruction, size suffixes 310 
braces ({}), alias command 44 
{} (braces) 

See braces (|(), alias command 
brackets ([]) 

array-slice parameter 27 
grep utility 219 

branch instructions, size suffixes 310 
break command 117-119 
examples 118-119 
options 117-118 

Break menu, menu items and command-line equivalents 
breakpoints 

cautions against incorrect use 74, 118, 155 
implementation 80 
setting 73-74, 83, 90 
BSR branch instruction, size suffixes 310 
-buffer command-line option 11 
build command, SC—SCMSG AREXX port 258 
Build menu, scmsg utility 254 
Build Project option, scmsg Build menu 254 
built-in functions 195-204 
See also specific built-in functions 
function reference 196-204 
parameters 195 
summary 196 
using 195-196 

buttons, hypergst utility 233-234 



c 

C functions 

See also calling assembler functions from C functions 
calling from assembler functions 330-331 
-c option 

diff utility 212 
grep utility 218 
smake utility 285 
C programs 

See also debugging C programs 
converting names to C++ names 211 

C+ + functions, declaring with asm keyword 328-329 

C+ + programs 

See also debugging C++ programs 
converting C names to C+ + names 211 
call command 120-121 
examples 121 
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calling assembler functions from C functions 322-330 
parameters = register option 326-327 
passing parameters on stack 323-326 
referencing global data 331-332 
returning values to calling function 329-330 
— asm keyword 327-329 

calling C functions from assembler functions 330-331 
Calls window 15 
caret ( A ), grep utility 219, 223 
case option, opt command 152 
catch command 81, 122 
examples 122 

catch option, opt command 152 
character classes, grep utility 221-223 
character constants, escape sequences 32, 35 
character strings, escape sequences 32, 35 
characters 

single, grep utility 221 
special, specifying with grep utility 225-227 
specifying number of times characters can appear, grep 
utility 222-223 
chess program 
debugging 69-72 
running 67-68 
chessl.cxx file 67 
source code 355-358 
chess2.cxx file 67 
child processes 
debugging 82-83 
finding Enforcer hits 83-84 
CHIP parameter, SECTION assembler directive 317 
class command, SC—SCMSG AREXX port 258 
clear command, SC—SCMSG AREXX port 258 
Clear option, scmsg Edit menu 255 
-cli command-line option 10, 11 
CNOP assembler directive 312 
Code Generation Options window 264 
CodeProbe debugger 3—37 
See also AREXX macros 
See also debugging programs 
basic features 4 
built-in functions 195-204 
command reference 109-194 
command summary 105-108 
compiling and linking programs 5-9 
debugging multitasking programs, operation 80 
debugging procedure 5 
displaying and setting options 42 
entering commands 18-35, 105 
function 36—37 
introduction 3 


multitasking features 4 
online help 17-18 
optimization 348 
quitting 36, 108 
running 9-13 
SC—CPR port 97 
specifying options 11-13 
Version 6.0 changes and enhancements xxi 
Version 6.50 changes and enhancements xxii 
windowing interface 13-17 
colon (:) 

location parameter 29 
smake utility 271 
-command command-line option 11 
command files 41-42 
-command option 
restart command 161 
start command 172 
command-line editing 19-20 
keys 20 

command-line options 
See also specific options 
cross debugger 103 
kernel 103 

supported by CodeProbe debugger 11-13 
commands 

See also specific commands 
aliases 43-46 

CodeProbe, command reference 109-194 
CodeProbe, summary 105-108 
command output in AREXX macros 96-97 
command-line editing 19-20 
debugging multitasking programs 81 
entering 18-20, 105 
entering escape characters 35 
extending across lines 19 
function keys 23-24 
menu accelerator keys 24-25 
multiple, on same line 19 
oml utility, specifying 246-247 
pull-down menus 20-23 
reentering without retyping 61 
specifying parameters 25-34 
comment field, assembly language source line 309 
comments, command files 41 
common subexpression merging 341 
communications 

ARREX interface 249, 256-261 
calling assembler functions from C functions 322-330 
calling C functions from assembler functions 330-331 
defining parameters for cross-debugging 103 
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communications ( continued ) 
establishing for cross-debugging 100 
referencing global data 331-332 
comparing files 
See diff utility 

Compilation option, scmsg Edit menu 255 
compiler 

See compiler options 
See sc command 
See scopts utility 
compiler options 
See also scopts utility 
running optimizers 346 
Compiler Options Index window 264 
Compiler Options window 264 
compiling programs 5-8, 49-50, 67-68 
config= option, scmsg utility 249 
constants 

assembler statements 311 
propagation and folding 343 
context option, opt command 152 
control flow transformations 344 
control sections, defining 317-322 
controlling program execution 107 
copy propagation 342 
cover utility 208-210 
example 209-210 
options 209 
coverage data 
See cover utility 

coverage option, cover utility 208-209 
cpr command 50, 69 
-cli command-line option 10 
CPRK 

command-line options 103 
copying 100 
starting 101 
terminating 104 
cprk command 101 
CPRX 

command-line options 103 
starting 101-102 
terminating 102, 104 
cprx command 
options 102 
-symfile option 102 
-x option 102 
cross debugger 
See CPRX 
See cross-debugging 


cross-debugging 99-104 
copying files 100-101 
debugging applications 103 
defining communications parameters 103 
establishing communications 100 
example using named pipes 104 
example using serial port 104 
preparing to use 100-101 
starting cross debugger 101-102 
starting kernel 101 

terminating kernel and cross debugger 104 
when to use 99-100 

CSECT assembler directive 313, 318-322 
parameters 318-319 
specifying addresses 319-322 
curly braces 

See braces ({}), alias command 
current message 250 
customizing, debugging environment 
See debugging environment, customizing 
-cx option, assembler 332-333 
cycles gadget 265 


D 

d array command 59 
d command, oml utility 246 
-d option 
assembler 333 
smake utility 286 
splat utility 293 

-d symbol ( = value) option, assembler 333 
data 

commands displaying 106 
commands modifying 106 
coverage, analyzing 208-210 
Data Items button 
hypergst utility 233 
dbptr macro 93 
dbstr macro 93 
DC assembler directive 313 
DCB assembler directive 313 
deactivate command 81, 123 
examples 123 
dead code elimination 341 
dead store elimination 341 
debug = full option 7 
generating H_DEBUG hunks 36 
debug =fullflush option 7, 8 



Index 377 


debugging C programs 49-65 
debugging example 50-65 
running example 49-50 
debugging C+ + programs 67-72 
debugging example 69-72 
running example 67-68 
debugging child processes 82-83 
debugging devices 88-92 
devices that do not create new tasks 88 
tasks created by devices 89-91 
UserDevInit routine 91-92 
debugging environment, customizing 39-48 
aliases 43-46 
command files 41-42 
commands 108 

displaying and setting options 42 
macros 46-48 
source file location 39-41 
debugging multitasking programs 79-92 
See also debugging devices 
catching tasks that are already running 85-88 
CodeProbe features 4 
CodeProbe operation 80 
commands 81, 108 
debugging child processes 82-83 
finding Enforcer hits in child processes 83-84 
redefining exception and trap handlers 80-81 
debugging programs 
See also cross-debugging 
See also debugging C programs 
See also debugging C++ programs 
See also debugging devices 
See also debugging multitasking programs 
basic steps 5 

debugging shared libraries 73-77 
displaying list of loaded libraries 74-75 
example 75-77 
setting breakpoints 73-74 
symload command 74 
tracing into shared libraries 75 
debug = line option 5-6 
generating H—DEBUG hunks 36 
debug = symbol option 6 

generating H—DEBUG hunks 36 
debug =symbolflush option 6-7, 8 
.DEFAULT fake target, smake utility 278 
default files, smake utility 283-284 
define command 46-48, 124 
examples 124 

#define statements, built-in functions 195-196 
delcomp command, SC_ SCMSG AREXX port 258 


delete block, diff utility 213 
Delete by..., scmsg Edit menu 255 
delete command, SC—SCMSG AREXX port 258 
Delete Message option, scmsg Edit menu 255 
delfile command, SC—SCMSG AREXX port 258 
delnum command, SC—SCMSG AREXX port 258 
demangle utility 211 
example 211 
dependent files 270 
detach command 81, 125 
examples 125 

-device command-line option 103 
devices 

See debugging devices 
devices macro 94 
devices option, opt command 152 
devs macro 94 

Diagnostic Message Options window 264 
Dialog window 14, 15 
escape sequences 32 
zoom mode 53-54 
diff utility 212-216 

error messages 215-216 
examples 214-215 
file-matching algorithm 351-352 
options 212-213 
dir= option, cover utility 209 
display command 51, 69-70, 126-127 
examples 126-127 
dollar sign ($) 

address parameter 26 
assembler statements 308, 311 
grep utility 219, 223, 226 
location parameter 28 
smake utility 274 
variable parameter 34 
driver.c file 89 
source code 369-370 
DS assembler directive 313 

dummy program, catching tasks that are already running 
85-86, 87 
dummy.c file 85 
source code 364 
dump command 59-60, 128-130 
aliases 129-130 
examples 130 
Help window 59-60 
dynamic option 

watch command 185 
wbreak command 186 
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dzero command 131 
examples 131 

E 

-e option, smake utility 286 
echo command 132 
example 132 

echo option, opt command 152 

Edit menu, scmsg utility 254-255 

editcommand command, scmsg utility 257 

editcommand option, scmsg Project menu 252 

editing, command-line editing 19-20 

ELSE assembler directive 313 

END assembler directive 313 

ENDC assembler directive 313 

ending programs 36 

ENDM assembler directive 313 

ENDM macro directive 316 

Enforcer hits 

debugging UserDevInit routine 91 
finding in child processes 83-84 
env command 133-134 
examples 134 
environments 15 

See also debugging environment, customizing 
run environment 191 

—EPILOG library function, sprof utility 299-300 
EQU assembler directive 313 
equals sign (=), smake utility 274, 275 
EQUR assembler directive 313 
error messages 
diff utility 215-216 
grep utility 227-229 
gst utility 232 
hypergst utility 234 
errors 

See error messages 
See scmsg utility 
escape sequences 

character strings and character constants 32 
entering 35 

example.device, debugging 89-91 
exception handlers, redefining 80 
exclamation point (!) 
grep utility 219, 223 
wlist command 193 
execbase macro 94 
executable file, dependencies 272 


execute command 41, 135-136 
examples 136 

executing code, controlling program execution 107 
exiting, Help window 60 
EXITM assembler directive 313 
EXITM macro directive 316 
expand command 47, 137 
examples 137 
expression parameter 28 
display command 126 
expressions 

assembler statements 310-312 
very busy expression hoisting 344 

F 

-f option 

grep utility 218 
lstat utility 237, 240 
smake utility 285, 286 
-F option, diff utility 212 
FAIL assembler directive 313 
fake targets, smake utility 277-280 
file command, SC_ SCMSG AREXX port 258 
file dependencies 
See smake utility 

File menu, menu items and command-line equivalents 
20-21 

File option, scmsg Edit menu 255 
files 

See also diff utility 

See also smake utility 

See also source files 

See also specific files 

applying patches 292 

copying for cross-debugging 100-101 

default, smake utility 283-284 

dependent 270 

diff utility file-matching algorithm 351-352 

executable, dependencies 272 

local input files, smake utility 281-283 

object, dependencies 272 

patch, generating 263 

target 270 

traceback, displaying 302-304 
Find icon, smfind utility 288 
finish command 138 
example 138 

floating-point instructions, size suffixes 309 
folding of constants 343 
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force option 
mkmk utility 242 
scsetup utility 268 
FORMAT assembler directive 313 
format parameter 

display command 126 
dump command 128-129 
fregister command 139 
examples 139 

func assembler module, calling assembler functions from C 
functions 323-326 
function, env command 133 
function keys 23-24 
function mode, command-line editing 19 
functions, built-in 
See built-in functions 
See specific built-in functions 


G 

gadgets, scopts utility windows 265-266 
global data, referencing 331-332 
global optimizer 339-344 
compiler options 346-348 
types of optimizations 339-344 
global symbol tables 
See gst utility 
See hypergst utility 
go command 55, 87, 140-141 
examples 141 
options 140 

Go to Alternate option, scmsg Edit menu 255 
Go to Error option, scmsg Edit menu 255 
gotofile command, scmsg utility 257 
gotofile option, scmsg Project menu 252 
gotoline command, scmsg utility 257 
gotoline option, scmsg Project menu 252 
greater than sign (>) 
diff utility 214 
grep utility 217 
lprof utility 235 
lstat utility 237 
omd utility 243 
oml utility 245 
tb utility 302 
> (greater than sign) 

See greater than sign (>) 
grep utility 217-229 
character classes, specifying 221-223 
error messages 227-229 


examples 220-227 

number of times character can appear, specifying 
223-224 
options 218 

pattern at beginning or end of line, specifying 224 
patterns containing special characters, specifying 
225-227 

single character, specifying 221 
specifying patterns 218-220 
gst utility 230-232 
error messages 232 
examples 231-232 
options 230-231 


H 

-h option, smake utility 286 
H-DEBUG hunks 36-37 
H—SYMBOL hunk 36 
help, online 17-18 
help command 17, 142 
examples 142 
Help window 15, 17-18 
dump command 59-60 
exiting 60 

hexadecimal numbers, specifying in assembler statements 
311 

hidden option 
scmsg Project menu 252 
scmsg utility 249-250 

hide command, SC_ SCMSG AREXX port 259 
Hide Window option, scmsg Project menu 254 
host machine 100 
hunks command 143 
example 143 
-hx option, assembler 333 
hypergst utility 233-234 
buttons 233-234 
error message 234 
hyphen (-), grep utility 219 


-i command-line option 11-12 
-i option 

assembler 333-334 
scompare utility 263 
smake utility 286 
ibytes option, opt command 153 
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IDNT assembler directive 313 
IF assembler directive 313 
IFC assembler directive 313 
IFD assembler directive 314 
IFEQ assembler directive 314 
IFGE assembler directive 314 
IFGT assembler directive 314 
IFLE assembler directive 314 
IFLT assembler directive 314 
IFNC assembler directive 314 
IFND assembler directive 314 
IFNE assembler directive 314 
.IGNORE fake target, smake utility 279 
ignorepath option, opt command 153 
INCLUDE assembler directive 314 
#include statement, smfind utility 289 
induction variable transformations 342 
init function 53-57 
Input window 16 

insert mode, command-line editing 19 
internal rules, smake utility 284 
ints macro 94 

invariants, moving invariants out of loops 342 


j 

-jc option, assembler 334 
-jm option, assembler 334 
jump command 144 
caution 144 
examples 144 


K 

-k option, smake utility 286 
kernel 
See CPRK 

keyboard shortcuts 24-25 
keys 

command line editing 20 
function keys 23-24 
menu accelerator keys 251 
special keys 24 

keysmenu accelerator keys 24-25 


L 


-1 option 
assembler 334 
diff utility 212 
tb utility 303-304 
-L option, diff utility 212 
label field, assembly language source line 308 
less than sign (<) 
diff utility 213 
oml utility 245 
< (less than sign) 

See less than sign (<) 
level, env command 133 
libraries 

See also debugging shared libraries 
See also oml utility 
link 244 

loaded, displaying list 74-75 
tracing into shared libraries 75 
libraries macro 94 
libs macro 94 

line command, SC—SCMSG AREXX port 259 
-line command-line option 11, 12 
line mode 

running CodeProbe in line mode 11 
search command 166 
link library 244 
link option, sc command 8, 36 
Linker Options window 265 
linking programs 5-8, 49-50, 67-68 
LIST assembler directive 314 
list command 145-146 
examples 145-146 
list option 
gst utility 230 
opt command 153 

Listing/Cross-Reference Options window 264 
lists gadget 265-266 
listsym command 147 
examples 147 

LLEN assembler directive 314 
load option 

opts command, SC—SCMSG AREXX port 260 
loading debug information 74 
local input files, smake utility 281-283 
location parameter 28-30 
log command 148-149 
examples 148-149 

loop program, catching tasks that are already running 
86-88 

loop.c file 85 
source code 364 


1 command, oml utility 246 



loops, moving invariants out of loops 342 
lprof utility 235-236 
advantages of sprof utility over 296 
examples 236 
lstat utility 237-241 
examples 238-241 
options 237 

M 

-m option, tb utility 303 
MACRO assembler directive 314, 316 
macros 46-48 
See also AREXX macros 
See also assembly language 
See also specific macros 
default 276-277 
defining 46-47, 274-275, 316 
displaying 47 

escaped macros not expanded 46 
hiding within double quotes 46 
overriding macro definitions 275 
removing 48 
smake utility 274-277 
sprof utility 298 
transformation rules 277 
using 316 
makeaptr macro 94 
makefile = option, mkmk utility 242 
makefiles 
See smake utility 
man macro 94 
Map Options window 265 
MASK2 assembler directive 314 
memcmp built-in function 197 
examples 197 

memcpy built-in function 198 
caution 198 
examples 198 

memmove built-in function 199 
caution 199 
examples 199 
memory macro 94 

Memory menu, menu items and command-line 
23 

Memory window 14, 16 
memset built-in function 200 
caution 200 
examples 200 


menu accelerator keys 24-25 
scmsg utility 251 
menus 

See also specific menus 
pull-down menus 20-23 
merge option, cover utility 209 
Message Number option, scmsg Edit menu 
Message window 16 
messages 

See also error messages 
current 250 
scmsg utility 250-251 
MEXIT assembler directive 314 
minus sign (-) 
grep utility 222 
smake utility 274 
mixed mode 

debugger used on optimized code 348 
opt source mixed command 7 
mkmk utility 242 
options 242 
mods macro 94 
modules command 150 
examples 150 
Modules window 16 
moving invariants out of loops 342 
multiple targets, smake utility 280 
multitasking programs 
See also debugging devices 
See also debugging multitasking programs 
asynchronous tasks 79 
synchronous tasks 79 
mylib.c file 75, 76 
source code 358 
mylib.fd file 75, 76 
source code 359 
mylib—pragmas.h file 75 
-mO option, assembler 334 
-m2 option, assembler 334 
-m3 option, assembler 335 
-m4 option, assembler 335 

N 

-n option 

grep utility 218 
oml utility 247 
scompare utility 263 
smake utility 286 
name= option, gst utility 231 
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name parameter 

CSECT assembler directive 3 18 

SECTION assembler directive 317 
named pipes, cross-debugging using 100, 103, 104 
NARG assembler directive 314 
networks, cross-debugging 100, 103 
newbld command, SC—SCMSG AREXX port 259 
newmsg command, SC—SCMSG AREXX port 260 
next command, SC—SCMSG AREXX port 259 
noautoedit option 

hide command, SC—SCMSG AREXX port 259 
NOFORMAT assembler directive 314 
NOLIST assembler directive 315 
-nommu command-line option 12 
nonfloating-point instructions, size suffixes 309 
NOOBJ assembler directive 315 
NOPAGE assembler directive 315 
-noprofile command-line option 12 
norexxonly option 

hide command, SC—SCMSG AREXX port 259 
nosource option, cover utility 209 
nostarter option, scsetup utility 269 
null modem cable, cross-debugging using serial port 100 
number command, SC—SCMSG AREXX port 258, 260 
number parameter 30 
number sign 

See pound sign (#) 

numeric mode, command-line editing 19 


o 

-o option 
assembler 335 
diff utility 212 
oml utility 247 
scompare utility 263 
spatch utility 292 
splat utility 293 
object files 
dependencies 272 
optimizing code 348 
Object Module Dissembler 243 
Object Module Librarian 
See oml utility 

octal numbers, specifying in assembler statements 311 
OFFSET assembler directive 315 
omd utility 243 
examples 243 
oml utility 244-248 
commands, specifying 246-247 


examples 248 
invoking 244-245 
options 247 
terminating 245 

.ONERROR fake target, smake utility 279 
online help system 17-18 
OpenDevice call 89, 91 

operand field, assembly language source line 308-309 
operation field, assembly language source line 308 
operations, reordering to reduce value lifetimes 344 
operators, assembler statements 311-312 
OPSYN assembler directive 315 
opt catch command 83 
opt command 42,151-156 
caution 155 
examples 156 
options 151-155 
opt radix command 30 
opt reslib on command 76 
opt search command 40 
opt source mixed command, mixed mode 7 
opt task command 81 
optalias option, global optimizer 346 
optcomplexity option, global optimizer 346 
optdepth option, global optimizer 346 
optimize nooptglobal option, running optimizers 346 
optimize nooptpeep option, running optimizers 346 
optimize optschedule option, running optimizers 346 
Optimizer Options window 264 
optimizing code 339-348 
global optimizer 339-344, 346-348 
peephole optimizer 345 
running optimizers 346-348 
scheduler 345 

source file correspondence with object files 348 
optinline option, global optimizer 346-347 
optinlocal option, global optimizer 347 
options 

See also Command-line options 
See also specific options 
displaying and setting 42 

Options menu, menu items and command-line equivalents 
21 

options results command 96-97 

optloop option, global optimizer 347 

optrdepth option, global optimizer 347 

opts command, SC—SCMSG AREXX port 260-261 

optsize option, global optimizer 348 

opttime option, global optimizer 348 

Output window 16 
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overwrite mode, command-line editing 19 


p 

-p option 
diff utility 213 
grep utility 218 
smake utility 286 
spatch utility 292 
PAGE assembler directive 315 
parameters 

See also specific parameters 
CodeProbe commands 25-34 
parameters on stack, passing 
calling assembler functions from C functions 323-326 
parameters = register option 
calling assembler functions from C functions 326-327 
patch files 

applying patches 292 
generating 263 
patterns, searching for 
See grep utility 
See splat utility 

pc option, symload command 175 
peephole optimizer 345 
percent sign (%) 
assembler statements 311 
scmsg utility 256 

period (.), grep utility 218, 221, 222 
-pipe command-line option 103, 104 
PLEN assembler directive 315 
plus sign ( + ), grep utility 219, 223 
portname option 

opts command, SC—SCMSG AREXX port 260 
scmsg Project menu 253 
ports macro 94 
pound sign (#) 

define command 124 
grep utility 223 
smake utility 271, 274 
undefine command 184 
#?, AmigaDOS wildcards 217, 288 
Preprocessor Symbols button, hypergst utility 234 
prev option 

opts command, SC—SCMSG AREXX port 261 
printArr function 51-52 
proc option, symload command 175-176 
proceed command 52, 157 
examples 157 


process.c file 82 
source code 360-362 

processes, catching processes that are already running 
85-88 

processl function, finding Enforcer hits 83-84 
profile option, sprof utility 298-299 
PROFT T.F. OFF macro, sprof utility 298 
PROFILE—ON macro, sprof utility 298 
profiling 

See also sprof utility 
lprof utility 235—236 
lstat utility 237-241 

program execution, commands controlling 107 
program parameter, tb utility 302 
programs 

See also cross-debugging 
See also debugging C programs 
See also debugging C++ programs 
See also debugging devices 
See also debugging multitasking programs 
debugging, basic steps 5 
determining time spent in functions 296-301 
Project menu 
scmsg utility 252-254 
scoptions utility 266, 267 
projects, setting up new projects 268-269 
—PROLOG library function, sprof utility 299-300 
propagation of constants 343 
Prototype Generation Options window 265 
Prototypes button, hypergst utility 233 
ps command 58, 158 
example 158 
public symbols 244 
pubscreen= option, scmsg utility 250 
pull-down menus 20-23 

menu items and command-line equivalents 20-23 


Q 

-q option 

diff utility 213 
grep utility 218 
smake utility 286 
question mark (?) 

#?, AmigaDOS wildcards 217, 288 
quiet option, break command 117 
quit command 36, 87, 159 
example 159 
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quit option 

opts command, SC—SCMSG AREXX port 261 
scmsg utility 250 

Quit option, scmsg Project menu 254 
quitting CodeProbe debugger 36, 108 
quotes, double (“”) 
alias command 44 
character strings 35 
grep utility 218 
macros 46 
smfind utility 289 
strings as program arguments 9, 10 
quotes, single (") 

assembler statements 311 
character constants 35 


R 

r command, oml utility 246 
-r option, tb utility 303 
radix option, opt command 153 
range parameter 30-31 
dump command 128 
rangelen option, opt command 153-154 
reductions in strength 344 
REG assembler directive 315 
regions macro 94 
register assignment 339-340 
register command 160 
examples 160 
register keyword 340 
register parameter 3 1 
Register window 14, 16 

relocatable expressions, assembler statements 312 
reordering operations to reduce value lifetimes 344 
report option, sprof utility 296, 298 
Reset to SAS/C defaults option 
scmsg Project menu 253 
scoptions Project menu 267 
reslib option, opt command 154 
resources macro 94 
restart command 55, 161-162 
caution 161 
examples 162 

Restore from global defaults option, scoptions Project 
menu 267 

Restore from SCOPTIONS option, scoptions Project menu 
267 


Restore from... option 
scmsg Project menu 253 
scoptions Project menu 267 
Restore option, scmsg Project menu 253 
return codes, AREXX macros 96 
return command 163-164 
cautions 163-164 
examples 164 
rexxonly option 

hide command, SC—SCMSG AREXX port 259 
opts command, SC—SCMSG AREXX port 261 
scmsg utility 250 
rflag command 165 
examples 165 

RORG assembler directive 315 

rsize parameter, CSECT assembler directive 318-319 

rsrcs macro 94 

rtype parameter, CSECT assembler directive 318 
run environment 191 

Run menu, menu items and command-line equivalents 22 


s 

-s option 

assembler 335 
grep utility 218 
oml utility 247 
smake utility 286 
splat utility 293 
tb utility 303 
SAS/C Macro assembler 
See assembly language 
SAS/C optimizer 
See optimizing code 
SAS/C utilities 
See specific utilities 

Save as global defaults option, scoptions Project menu 266 
Save As... option, scmsg Project menu 253 
Save as... option, scoptions Project menu 266 
save option 

opts command, SC—SCMSG AREXX port 260 
Save option, scmsg Project menu 253 
Save to SCOPTIONS option, scoptions Project menu 266 
sc command 267, 332 
generating H_ SYMBOL hunks 36 
link option 8, 36 
SC-CPR port 97 

SC—SCMSG AREXX port, scmsg utility 257-261 
scheduler 345 
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scmsg utility 249-262 
Build menu 254 
Edit menu 254-255 
examples 262 

invoking editor with AREXX 256-257 
message format 251 
options 249-250 
Project menu 252-254 
SC-SCMSG AREXX port 257-261 
scompare utility 263 
example 263 
options 263 
scopts utility 264-267 
exiting without saving changes 266 
gadgets 265-266 

loading previously saved options files 267 
resetting options to default values 267 
saving option settings 266 
specifying options without gadgets 266 
tasks performed 267 
windows 264-266 
-screen command-line option 12 
screen option 

opts command, SC—SCMSG AREXX port 260 
scsetup utility 10, 268-269 
options 268-269 
running from Shell 269 
running from Workbench 269 
search command 166 
examples 166 
line mode 166 
windowing mode 166 
search option, opt command 154 
SECTION assembler directive 315, 317-318 
parameters 317 
specifying addresses 317-318 
seg option, symload command 176 
SegTracker, debugging UserDevInit routine 92 
select option 

opts command, SC—SCMSG AREXX port 261 
semicolon (;) 
lias command 44 
alias command 44 
define command 48 
cho command 132 

entering several commands on one line 19 
serial port, cross-debugging using 100, 104 
serial.c file 89, 90 
source code 364-368 
SET assembler directive 315 


set command 59, 167-168 
examples 167-168 
.SET fake target, smake utility 279 
Set Options option, scmsg Project menu 252-253 
shared libraries 

See also debugging shared libraries 
tracing into shared libraries 75 
Shell 

catching tasks started from Shell 85-87 
running CodeProbe 9 
running scsetup utility 269 
running smake utility 285 
running smfind utility 288 
running sprof utility 296, 297 
show command 170 
example 170 
show option 

opts command, SC—SCMSG AREXX port 261 
showcli macro 94 
showprocess macro 95 
.SILENT fake target, smake utility 280 
size field, assembly language source line 308 
size suffixes, assembler statements 309-310 
slash (/), assembler 334 
sleep command 169 
example 169 
slink 8-9 

stripdebug option 9 
slink command 
addsym option 36 
generating H_ SYMBOL hunks 36 
smain.c file 49, 50 
source code 353-354 
smake utility 76, 270-287 
alternate targets 280-281 
creating and using default files 284 
creating makefiles 271-283 
default files 283-284 
default macros 276-277 
fake targets 277-280 
internal rules 284 
local input files 281-283 
macros 274-277 
multiple targets 280 
options 285-287 

overriding macro definitions 275-276 
running 285-287 
special symbols 274 
transformation rules, defining 277 
smakefile file 76 

smcomm interface, smfind utility 289-290 
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smfind utility 288-291 
AddSCMSG function 290 
examples 291 
running 288-289 
smcomm interface 289-290 
sort program, debugging 50-63 
sort.c file 49 
source code 354-355 
source code 

chessl.cxx file 355-358 
driver.c file 369-370 
dummy.c file 364 
loop.c file 364 
mylib.c file 358 
mylib.fd file 359 
process.c file 360-362 
serial.c file 364-369 
smain.c file 353-354 
sort.c file 354-355 
swap.c file 355 

test.c file (for child processes) 362-363 
test.c file (for shared libraries) 359 
source command 40, 171 
examples 171 
source files 

commands displaying 106 
dependencies 272 
optimizing code 348 
setting location 39-41 

source line fields, assembly language 308-312 
source option, opt command 154 
Source window 14, 16, 23 
sourceis compiler option 40 
spatch utility 292 
example 292 
options 292 

SPC assembler directive 315 
SPECIAL gadget 266 
special keys 24 

-speed command-line option 103 
splat utility 293-295 
examples 293-295 
options 293 
sprof utility 296-301 
advantages over lprof utility 296 
autoinitialization and autotermination functions 298-299 
examples 300-301 
operation 299-300 
profile option 298-299 
report format 297-298 


report option 296, 298 
running 296-297 
start command 172-173 
caution 172 
examples 1 73 

-startup command-line option 12-13 
-startup option 

quit command 159 
restart command 161 
start command 172 

statements, writing assembler statements 308-312 
static option 

watch command 185 
wbreak command 186 
statistics utilities 
lprof utility 235-236 
lstat utility 237-241 
status codes, AREXX macros 96 
status macro 95 
strcat built-in function 201 
caution 201 
examples 201 
strcmp built-in function 202 
examples 202 
strcpy built-in function 203 
caution 203 
examples 203 
strength, reductions 344 
string parameter 32 
strings 

See smfind utility 
See splat utility 
strings gadget 265 
stripdebug option, slink 9 
strlen built-in function 204 
examples 204 

strlen option, opt command 154 
Structs/Unions/Enums button, hypergst utility 234 
subrange parameter 33 
swap function, debugging 63-65 
swap.c file 49 
source code 355 
symbol command 174 
example 174 

symbol = option, gst utility 231 
-symfile option, CPRX command 102 
symload command 74, 81, 86, 91-92, 175-176 
examples 176 
options 175-176 
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synchronous tasks 79 


T 

-t option 

lstat utility 237, 241 
oml utility 247 
smake utility 286 
tab option, opt command 154 
target files 270 
target machine 100 
target = option, mkmk utility 242 
targets, smake utility 
alternate 280-281 
fake 277-280 
multiple 280 

task option, opt command 155 
tasks, catching tasks that are already running 85-88 
tasks command 81, 83, 177-178 
examples 178 
tb utility 302-304 
examples 303-304 
options 303 

temp option, break command 118 
templates, invoking editor with AREXX 256 
test program 
debugging 82-83 
finding Enforcer hits 84 
test.c file (for child processes) 82 
source code 362-363 
test.c file (for shared libraries) 75, 76 
source code 359 
text option 

opts command, SC—SCMSG AREXX port 261 
top option 

opts command, SC—SCMSG AREXX port 261 
trace command 55-56, 75, 179 
examples 179 

trace option, break command 117 
traceback information, displaying 302-304 
tracing into shared libraries 75 
transformation rules, smake utility 277 
trap handlers, redefining 81 
ts command 180 
examples 180 
TTL assembler directive 316 
type parameter 33 
CSECT assembler directive 318 
SECTION assembler directive 317 


Typedefs button, hypergst utility 233 

u 

-u option 
assembler 335 
smake utility 287 
tb utility 303 
unalias command 181 
examples 181 

unassemble command 182-183 
examples 182-183 

unassemble option, opt command 155 
undefine command 48, 184 
examples 184 
underscore (_ ) 
assembler statements 308 
calling assembler functions from C functions 328 
-unit command-line option 103 
unload option, gst utility 231 
Use option, scmsg Project menu 253 
UserDevInit routine, debugging 91-92 
UserLibCleanup, debugging 75-77 
UserLiblnit, debugging 75-77 
utilities 

See specific utilities 


v 

-v option 
grep utility 218 
oml utility 247 
splat utility 293, 294 
tb utility 303 
-V option, grep utility 218 
variable parameter 34 
variables 

assembler statements 310 
auto variable elimination and remapping 343 
verbose option, gst utility 231 
very busy expression hoisting 344 
View menu 17 

menu items and command-line equivalents 22 

w 

-w command-fine option 13 
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-w option 
assembler 335 
diff utility 213 
smake utility 287 

wait option, scmsg Project menu 253 
warnings 

See scmsg utility 
watch command 62, 185 
examples 185 
options 185 

Watch menu, menu items and command-line equivalents 
23 

Watch window 14, 16-17, 62-63 
-wb command-line option 13 
wbreak command 186 
examples 186 
options 186 
wclear option 187 
examples 187 

-wdialog command-line option 13 
wdisable command 188 
examples 188 
wendable command 189 
examples 189 
whatis command 190 
examples 190 
when option 
break command 117 
go command 140 
where command 191 
examples 191 
whichis macro 95 
window command 17, 192 
examples 192 
windowing interface 13-17 
See also specific windows 
active window 13-17 
closing windows 17 
opening windows 17 
windowing mode, search command 166 
windows 

See also specific windows 
scopts utility 264-266 
wlist command 193 
example 193 
wmsg command 194 
examples 194 
Workbench 

catching processes started from Workbench 87-88 
running CodeProbe 10 
running scsetup utility 269 


running smake utility 285 
running smfind utility 288-289 
running sprof utility 296-297 
starting cross debugger 102 
-wregister command-line option 13 
-wsource command-line option 13 
-wwatch command-line option 13 

x 

x command, oml utility 246 
-x option 

copying programs for cross-debugging 104 

CPRX command 102 

oml utility 247 

smake utility 287 

stripping debug information 101 

tb utility 303 

XDEF assembler directive 316 
XREF assembler directive 316, 320 


z 

-z option, lstat utility 237, 239 
zoom mode, Dialog window 53-54 


Special Characters 

$ parameter, dump command 128 
-$ option, grep utility 218 
@ command, oml utility 247 
/ (slash) 

See slash (/), assembler 
\ (backslash) 

See backslash (\) 

= (equals sign) 

See equals sign (=), smake utility 
(quotes, double) 

See quotes, double (“”) 

[] (brackets) 

See brackets ([]) 

. (period) 

See period (.), grep utility 
+ (plus sign) 

See plus sign (+), grep utility 
& (ampersand) 

See ampersand (&) 



Index 389 


! (exclamation point) 

See exclamation point (!) 

$ (dollar sign) 

See dollar sign ($) 

* (asterisk) 

See asterisk (*) 

; (semicolon) 

See semicolon (;) 

A (caret) 

See caret ( A ), grep utility 
- (hyphen) 

See hyphen (-), grep utility 
% (percent sign) 

See percent sign (%) 
—(underscore) 

See underscore (_ ) 

? (question mark) 

See question mark (?) 

' (backtick character) 

See backtick character 0 
" (quotes, single) 

See quotes, single (*’) 

: (colon) 

See colon (:) 

# (pound sign) 

See pound sign (#) 

@ (at sign) 

See at sign (@) 
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